Re: [pps-comment] TAB Reviewer for PPS-Core-Elements-1.0, PPS-Transaction-Message-1.0,PPS-Profile-Specifications-1.0

[Yasuyuki Nishioka <nishioka@hosei.ac.jp>]

Dear Patrick,

Thank you for your comments and suggestions.
All of them are very helpful for us.
Personally, I would start reading documents
you suggested, and try to learn the style of
most useful and valuable documentations in the
world.

Short notes I would say for your comments are:
first, we intentionally use "SHULD" as the
definition in RFC 2119. According to Part 1,
PPS allows a software to use "id" attribute that
is not an identifier of the object (not XML
element but real world object or record of RDB
etc.). Semantic definition is agreed among
parties by profile specifications defined in
Part 3.

The basic idea behind is that validation software
doesn't need only XML schema, but also profile
informations that cover semantic mapping between
software applications. I'm not sure that success
of communication can be defined either in computer
level or business level.

In terms of conformance, we defined a method to
clarify whether of not a document is conform with
our specifications. Then one party try to check that
a document written by other party is consistent
with the normative text. Doesn't it still make sense?
Sorry, I should ask after I will read the
ConformanceGuidelines again.

Anyway, I think we need to have more time to
elaborate all our specification and check them
carefully to improve the document quality.

After the next F2F meeting, we report the result
of decision by the PPS committee.

Best regards,

Yasu

Chair of PPS TC

Patrick Durusau wrote:
> Greetings!
> 
> One of the more interesting duties I have as an OASIS TAB (Technical 
> Advisory Board) member is being assigned to return comments on work in 
> OASIS that is up for public review. It gets me out of my markup backyard 
> and to look at work I would not normally see. (What follows are my 
> opinions and not those of the TAB.)
> 
> Unfortunately that sometimes means I have to point out problems that I 
> think OASIS should have mechanisms to help TCs catch earlier in the 
> standards process.* This is one of those times.
> 
> All three documents cite RFC 2119 (http://www.ietf.org/rfc/rfc2119.txt).
> 
> There the word SHOULD is defined as:
> 
>> 3. SHOULD   This word, or the adjective "RECOMMENDED", mean that there
>>     may exist valid reasons in particular circumstances to ignore a
>>     particular item, but the full implications must be understood and
>>     carefully weighed before choosing a different course.
>>    
> 
> If we take the second and third sentences of 2.1 Structure of primitive 
> elements
> 
>> The type of this element SHOULD be represented with the following XML 
>> schema and SHOULD fulfill the following constraints.
> and
>> id attribute SHOULD represent an identifier of this element.
> 
> It is fairly clear that SHOULD is the wrong term to use.
> 
> What is literally being said for the "id" attribute is that it "should" 
> represent "an identifier of this element," but it could also represent 
> the identifier for some other element or some other value altogether, so 
> long as "...the full implications [are] understood and carefully 
> weighted before choosing another course."
> 
> All three documents have extensive and incorrect use of the term "SHOULD."
> 
> Personally I don't bother with normative language for attributes and 
> simply state them. The <blort> element attributes are: <listHere>.
> 
> That means that you can define conformance as conforming to element 
> <blort> as defined and its children or whatever.
> 
> The use of "SHOULD" returns to bite you in the conformance clauses.
> 
> 9 Conformance (of PPS-Core-Elements-1.0) reads:
> 
>> A document or part of document confirms OASIS PPS Core Elements if all 
>> elements in the artifact are consistent with the normative text of 
>> this specification, and the document can be processed properly with 
>> the XML schema that can be downloaded from the following URI.
> 
> Yes, but we have already seen any text could be consistent with the 
> normative text. A standard full of shoulds really isn't a standard at all.
> 
> For all three documents I would suggest that you review: 
> http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html.
> 
> It is also problematic when you say "consistent with the normative 
> text." Not sure what that means.
> 
> Not my area so I don't know what parts of the standards I shall conform 
> to, etc.
> 
> BTW, should your ID attributes be xsd:string?
> 
> The word "description" is mis-spelled in the schema fragments in 4.2, 
> 4.3, 4.6, as "descirption." (In PPS-Profile-Specifications-1.0)
> 
> Question: Have the examples been checked against the schema with 
> validation software? Just asking. I didn't try to parse them out by hand.
> 
> ****
> 
> Some style comments that aren't critical but suggestive:
> 
> The schema is required to be available as a separate electronic document 
> so I would lose the embedded schema. Particularly since you repeat the 
> same information immediately after each fragment in prose.
> 
> I would then split up all the attributes and define each one once 
> instead of for each element. Plus put the attributes in numbered 
> subsections so they can be easily referenced. See ODF part 1 for an 
> example of this style. (Yes, I am the editor. ;-) ) Like I said, style 
> comments which are ultimately personal choice. See what works for you 
> and your community.
> 
> I did not proof the documents with a spell checker but I would suggest 
> doing so, particularly since I did find a spelling error in the schema 
> for PPS-Profile-Specification-1.0. More of a schema typo than anything 
> else but would not hurt to check the rest of the documents.
> 
> Hope everyone is looking forward to a great weekend!
> 
> Patrick
> 
> * That is not a universally held opinion at OASIS but it is mine.
> 

-- 
Yasuyuki NISHIOKA, Ph.D.
Professor of HOSEI University
2-17-1 Fujimi Chiyoda-ku Tokyo Japan, 102-8160
Phone: +81-3-5228-1425, Fax: +81-3-5228-1412