Re: [sdo] ISSUE 164: SDO Compliant Documentation

[Bryan Aupperle <aupperle@us.ibm.com>]

Lines with  MAYs that need review:

There is a set dealing with throwing
exceptions (380, 413, 549, 553, 554, 1013, 1628 and 1648).  While
these are OK, there may be a better way to discuss error handling once
and not have all of these individual MAYs.

There is a set dealing with the language
specs (244, 245, 263 and 264).  Unless we make language specifications
conformance targets (not the SCA pattern), we need reword these.

711-713 and 1488-1489 should be reworded.

Ones that are not really normative statements:
130, 335, 421 (lower case), 491, 672, 844, 1011, 1161 (lower case), 1567
(lower case), 2114&2115, 2201 (lower case).

2343 has a wording problem

Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect

Research Triangle Park,  NC 
+1 919-254-7508 (T/L 444-7508)
Internet Address: aupperle@us.ibm.com

From:	"Barack, Ron" <ron.barack@sap.com>
To:	<sdo@lists.oasis-open.org>
Date:	08/14/2009 09:45 AM
Subject:	[sdo] ISSUE 164:  SDO Compliant Documentation

---

Hi Everyone,

As discussed, I've created a JIRA issue to discuss this:
http://www.osoa.org/jira/browse/SDO-164

As promised, I've uploaded a first pass at the core spec here:  http://www.oasis-open.org/apps/org/workgroup/sdo/download.php/33803/sdo-core-090814.doc

The version has an appendix where the compliance points are listed, with links to the relevant sections of the spec…I believe that this is what Brian was referring to when he said we should copy what was done in the SCA assembly TC.

I've used the keyword MUST to indicate a compliance point for the implementation.  I tried to keep these limited to stuff for which I could imagine writing a test.  For constraints on application, I used "requires".  I noticed that the SCA spec also has compliance points on things like the SCDL files, so it seemed OK to use 2119 language here.  The appendix contains only MUSTS.

Of course I had to make a bunch of editorial changes, and as I was going thru I reworked some paragraphs that I thought were unclear.  I tried not to alter the meaning of anything, only to clarify, but this requires everyone review the changes.  The only big change was that I removed section 4.2.7, on change summary serialization, to chapter 11 (ChangeSummary XML Format).  

Best Regards,
Ron