sdo message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: [sdo] ISSUE 164: SDO Compliant Documentation
- From: Bryan Aupperle <aupperle@us.ibm.com>
- To: sdo@lists.oasis-open.org
- Date: Fri, 14 Aug 2009 11:35:29 -0400
First pass comments:
MAY statements are normative and need
to be labeled.
There appear to be some MAY statements
that are not normative and should be reworded. A MAY statement should only
be used to define what a conformance target can optionally implement; not
to identify something it might encounter but is still required to support
if is encountered. (I'll work on a specific list for a subsequent note).
We need to decide on the set of conformance
targets (each normative statement relates to a target, and the target should
be identified). Clearly one target is an SDO implementation. Since
we define annotations and XML extensions, we can consider various types
of documents as targets. User applications would not normally be
a target (i.e. applications would not normally claim to conform to the
spec)..
Using "requires" for statements
about end user code is a bit problematic RFC 2119-wise. A statement
of the form: "An application has to ..." is better.
The SCA specs use bi-directional bookmarks
and highlighting for the normative statements. The actual text is
in the table in the appendix and is highlighted with shading. This
text is then linked to, via a bookmark, in the running text. This
makes it easy to see the entire statement in the running text in all formats
(without the shading, the statements are not distinguishable from normal
text in the PDF format). The label is defined in the running text
and linked to in the table (as Ron has already done).
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]