Re: [ubl-ndrsc] First cut on Design Document

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

I have put Mark's document on our page (and I will put successive drafts 
here using the same naming scheme, unless someone has a suggestion for a 
different one):

   http://www.oasis-open.org/committees/ubl/ndrsc/drafts/ndr-20011112.doc

Here are some semi-random comments and reactions as I read through it.

Position paper management: I'd like to see the names of champions put into 
the relevant section headers.

General style: It would be great if the blue quoted stuff could be 
attributed in some simple manner (a one-line attribution or link), because 
I'm not familiar with most of the sources you're quoting.  Also, this is a 
tiny thing, but I would prefer it if the headers were all left aligned and 
if a TOC could be provided.

Design principles: We need to put the already-agreed-on design principles 
somewhere.  Would they go in Section 3.3?  Sections 4.5-4.11?  Assuming we 
come up with a bunch of ranked use cases tomorrow, where would they 
go?  One of these sections?

General rules: Section 5.1 seems to take a stab at some "universal" 
rules.  Did this come from another source, or are these essentially your 
recommended positions on these issues?  I don't see any reason to keep 
these separate from the other categories of rules.  I would say that 1, 2, 
8, 9, and 10 are all "XML usage" rules.  3 and 6 are naming rules.  4, 5, 
and 7 are rules about the relation between messages and BPs.  12 is an 
element/attribute rule.  13 and 14 are related to datatypes.  I'm not sure 
what 15 is trying to say.  All of these categories I mention would make 
dandy sections or subsections, if they're not already.

Section 5.2: Did these come from some other source?  If not, Mark, do you 
want to be the champion for this issue? :-)

Section 5.2.2: I'm not sure that "Standardization" is unambiguous in this 
context!  I think it would be useful to have a Simple Datatypes section 
that incorporates this stuff.  It's sort of about naming, but it's mostly 
about enumeration.  (Then 6.9 and 6.10 could maybe go there too.)

Section 6: I think "Messages" is too broad a topic on which to have a 
top-level section.  Is there a way to break it down more, so that we can 
avoid hugely nested subsections?

Section 6.7.1: I think it would be useful to distinguish between simple and 
complex datatypes.

Section 6.7.3: How different are 6.7.3.1 and 6.7.3.2?  Does "Standardized" 
in 6.7.3.3 mean "common"?  What does 6.7.3.4 "Categories of usage" mean?

Documentation and appinfo: I would put a section for these in Section 6 (as 
you've currently organized it), not 7.12.  It's not about features so much 
as conventions for what to put in there, so we can generate the outputs we 
need.

Schema feature analysis: Eventually, I imagine that we'll combine Annexes A 
and B.  I'm not sure we should actually list the test schemas; easier and 
more maintainable to point to these.

Thanks, Mark!  This looks like a juicy start.

         Eve

At 08:38 AM 11/12/01 -0500, CRAWFORD, Mark wrote:

>Greetings,
>
>The attached file contains my first cut on the design document outline 
>with cut and paste of various discussions.  It was rather difficult to put 
>together from the many inputs we had, and in many cases it was hard to 
>decide where to best place a topic (especially between Chapters 6 
>(intended to be more structure) and 7 (intended to be more syntax 
>specific) since the input documents do not necessarily agree.  Please feel 
>free to provide comments and suggestions. Our goal is a good design 
>document, and I am thick skinned and have no pride of authorship, so don't 
>hold back.
>
>Mark

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