[ubl-ndrsc] Re: [ubl-comment] ARTS comments on NDR dist #2

["Eve L. Maler" <eve.maler@sun.com>]

Herewith, some responses (which I will forward to the commenters):

Eve L. Maler wrote:
> FYI-- The following comments from the ARTS (retail) organization were 
> sent on NDR distribution #2.  I will try to respond to as many points as 
> possible in a followup posting.  Many thanks for the comments!
> 
>     Eve
> 
> -------- Original Message --------
> You asked for comments, my first set of comments are about the document
> presentation. As you will be aware this is a particular bug-bear of
> mine.  If any standards committee is producing multiple documents, then
> the documents should look like they form part of a coheren, well-thought
> out whole.  Major presentation inconsistencies between supposedly
> related documents impedes acceptance.
> 
> *_Document Presentation:_*
> First up the package contains six PDF files and although the content
> seems to be good:
> *a.* One document is still an SAP internal document not using the OASIS
> template
> 
> *b.* There are two different versions of the OASIS logo in use.
> 
> *c.* A couple of documents are obviously written by someone for whom
> English is not a first language, the consequent grammar mistakes make
> the documents very difficult to read.
> **
> *d. *There is no consistency in how XML and XSD Schema fragments are
> presented in the various documents. As this is an XML initiative, it is
> not unreasonable to expect that XML & XSD Sschema fragments would be
> presented in a 'house style'.

We do have a goal to make all our outputs more professional-looking and 
consistent in our next distribution, so your comments are a timely 
reminder of items we have to take care of.  A bit of context may explain 
how they got to be the way they are:

Although our position papers are starting to reach more consistency of 
style, they represent individual opinions and not (typically) group 
consensus and so we haven't been putting as much emphasis on their 
style.  A new template became available for publishing OASIS documents, 
and (mea culpa -- I'm the author of the template!) the first version 
used the wrong OASIS logo.  Because some of these position papers have 
been around for months, though, some use the style they originally 
started with, before we took advantage of any stylistic guidance.

> *__*
> *_Global vs. Local:_*
> *a.* The abstract doesn't inform the reader that the document is a
> proposal to change a previous guideline.
 >
> *b.* Lines 46 & 47 of the introduction states the original guideline but
> does not (and should) continue with a short statement of the problems
> that this guideline has created. Introduction should conclude with a
> short statement that the remainder of the document proposes a solution
> to these problems.
> 
> *c. *Although the example XML instance documents on lines 268 - 300
> illustrate the problem being solved: (extension writers end up having to
> qualify every name in every instance document).  The problem is never
> stated, and nor are the ramifications and likely consequences of those
> problems discussed.
> 
> *d.* Line 402 "4.2  Globally Qualified Solution"   should be "4.2 An
> Alternative Solution", make it clear that this is a proposal for change.
> 
> *e.* The author has decided he (she?) is proposing one solution to the
> stated problem. Are there other ways of extending the UBL schemas with
> out having to us name-space qualifiers everywhere?  If so then more
> possibilities should be discussed. It is after all a position paper,
> which is attempting to convince the reader to agree with the author.

This paper is in its very early stages.  We'll make sure all your very 
good comments get discussed.

> *__*
> *_Facets:_*
> *a.* This document is obviously a very early working draft, it needs to
> include a description of what facets are, with an example, and why they
> need to be used, perhaps just http: link to appropriate W3C documentation.

You're right that it's an early draft; it's still at V01.

You bring up a good question about how much we should update our 
position papers once we decide on the relevant set of recommendations. 
To be honest, the position papers are largely an "internal" device that 
we've been exposing in review distributions in order to get feedback on 
the technical content.  It's been a bit of a resource struggle to update 
them thoroughly to keep up with actual decisions made by the group. 
They also often assume a fairly high level of XSD knowledge, as you note.

For example, it has been suggested to the author of the facets paper 
that it should be merged over into the main NDR document with a fuller 
explanation of the details of our recommendations around "pairs" of 
datatypes for Core Component Types, since the NDR document doesn't 
really cover that yet and the facets rationale for this is just one 
(though the most important) rationale.

My hope has been that the position papers would stand as good "rationale 
documents" once the NDR document is complete, but resource constraints 
may make this a bit of a challenge.  I'd be interested to hear feedback 
on whether people really need them to be "finished/polished" as 
documents or whether we should just try to set expectations differently.

> *_Code Lists_*
> *a.*  Line 67, a reference to the guideline outlining the use of 'Codes'
> in UBL is appropriate.  Other XML vertical initiatives have decided that
> codes are to be used in a very limited fashion (if at all). A reader new
> to UBL may need such a reference.

I confess I hadn't thought of recommending that code use be limited; we 
have assumed that code use would be fairly extensive, since codes are 
shortcuts for well-documented semantics that UBL would get to use "for 
free".  Can you comment more on why the other initiatives you're 
familiar with decided to steer clear of them?

The actual "content" decisions (e.g., minimum requirements for 
supporting specific actual code lists, and the choices of which 
components should be code-containing) need to be made by our Library 
Content Subcommittee, so the NDR group hasn't ventured there to date.

> *_Elements vs. Attributes_*
> *a.* * *There appears to be no rules about removing words deemed to be
> spurious because of the hierarchical nature of XML, Example:
> <Order>
>     <OrderHeader>
>         <From/>
>         <To/>
>     </OrderHeader>
>     <OrderBody>
>         <OrderLineItem/>
>         <OrderLineItem/>
>     </OrderBody>
> </Order>
> 
> Could become, because the XML nesting hierarchy provides sufficient 
> context.
> <Order>
>     <Header>
>         <From/>
>         <To/>
>     </Header>
>     <Body>
>         <LineItem/>
>         <LineItem/>
>     </Body>
> </Order>

Just such a recommendation is encapsulated in our naming rules 
(appearing in the NDR document itself, but formerly hashed out in our 
old "tag structure" position paper, a paper that we've agreed not to 
update to match our decisions).  By requiring that the object class name 
not be part of the name of an element, we allow for just such 
elision/reuse opportunities.

The elements vs. attributes paper was created to help us settle the 
age-old question of when to choose one over the other.  By the way, it 
turns out that we have more work to do in this area, to cover the 
situations where a supplementary component of a Core Component Type 
itself requires supplementary components.  One of the inelegant things 
about XML, unless you never use attributes... :-)

I hope that these responses have been helpful.  We would be glad to take 
a look at any further comments.

Regards,

	Eve

-- 
Eve Maler                                    +1 781 442 3190
Sun Microsystems XML Technology Center   eve.maler @ sun.com