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

[Patrick Durusau <patrick@durusau.net>]

Dear Yasu,

Thanks for the quick reply!

Another comment or two below.

On 3/13/2010 12:24 AM, Yasuyuki Nishioka wrote:
> 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.
>
I remain puzzle by your use of "should" for a couple of reasons.

The following comments may help your committee make clear the reasons 
for its choice.

When you say that semantic definition is agreed among the parties, I 
would agree but for part 3 also using "should" which leaves even the 
terms of the semantic definition itself up to agreement.

Hmmm, trying to think of a clear example, ... the following which may or 
may not be helpful:

Say that I have two parties that are trying to exchange information that 
depends on what is meant by the terms red, blue and green.

OK, so we write a standard that says,

1) If you mean "red" then you should use the string #FF0000

2) If you mean "blue" then you should use the string #0000FF

3) If you mean "green" then you should use the string #008000

And, in the profile part we say:

4) You should use "red" to mean #FF0000

5) You should use "blue" to mean #0000FF

6) You should use "green" to mean #008000

Now, remembering that these are *all* the terms we have defined:

Party A sends to party B a profile that says:

-- blue means #00FF00 (lime actually)

Which is perfectly permitted by the "should" clauses we have defined for 
the normative standard and the profile.

But, I don't suspect it is what we intended when we wrote the standard.

That is to say even though we want to *enable* the declaring of a 
semantic between parties with a profile mechanism, that profile 
mechanism is using definitions that have boundaries that are expected 
between any parties that are using the standard.

I would expect the definitions in parts 1 and 2, therefore, to *not* use 
"should" as those are the foundational semantics to be interchanged.

I would not expect a profile to use "should" but rather to allow 
*defined alternative choices* to be declared so that a user is always 
certain of the choices that may be communicated to them.

One of the principles of markup that isn't discussed as often now as say 
twenty years ago (blush, I am showing my age) is the need for *blind 
interchange.* That is markup should not depend on private or out of band 
understandings of the semantics of the markup.

Each such understanding *decreases* the value of the markup and, perhaps 
more importantly, *increases* the cost of using the standard for every 
user. The cost of use increases because the user must ascertain the 
semantics of every instance of markup they encounter, which greatly 
increases the cost of using that particular markup system.

Imagine if for every document in OpenDocument Format or OpenXML format 
you received that your application depended upon discovering what was 
meant by the markup in that particular document. It isn't hard to see 
that the seamless interchange of documents and spreadsheets upon which 
we depend every day would quite rapidly breakdown.

That is the increase in cost side. The decrease in value is no less 
important from the standpoint of adoption of your standard. Why would I 
want to use a standard where I have to take additional steps simply to 
have others understand what I meant? Steps beyond what the standard 
requires? That makes decreases the value of the markup to me as a user.

Apologies for the length of that comment! Some of the original traffic 
on issues like this went on and on and on. It is a difficult issue and 
one that we need to get right so that others can benefit from your work.

> 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.
>
Well, yes, there are limits even to what can be expressed in standards 
but then we don't write standards for things that cannot be communicated 
or standardized. Or at least we shouldn't. Reasonable people will 
disagree as to exactly where that boundary lies.

Hope you are at the start of a great week!

Patrick
> 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.
>>
>

-- 
Patrick Durusau
patrick@durusau.net
Chair, V1 - US TAG to JTC 1/SC 34
Convener, JTC 1/SC 34/WG 3 (Topic Maps)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)