Re: [ubl-csc] (2) Review packaging

[Jon Bosak <Jon.Bosak@Sun.COM>]

[Eve:]

| Sorry to ask dumb questions (I'm sort of out of the loop at this
| point), but...  I'm confused about the notion of making the Naming
| and Design Rules just be a "chapter 3" of some larger document; as
| it is, it already nests pretty deeply.

[Mark:]

| I strongly disagree with infusing the NDR document into a larger
| package.  They must remain separate, as they are in fact separate
| focuses.  To meld them together will result in resistance to
| library based on NDR, and to NDR based on library. True the
| library content is (should be) based on the NDR document, however
| the NDR document is in fact a stand-alone document that can
| operate completely independently from library content.

I think there's some confusion here around the words "package" and
"document."

When UBL is published as an International Standard, it will likely
consist of three parts:

   Universal Business Language -- Part 1: Naming and Design Rules
   Universal Business Language -- Part 2: Library Content
   Universal Business Language -- Part 3: Context Methodology

Each of these parts will constitute a separate, standalone
document.  No one is suggesting that we subsume any of these
pieces within any of the others.

Our task this week is to make two of these *documents* (Part 1 and
Part 2), together with a fairly large number of supporting pieces,
available to reviewers as a single *package* that can be
downloaded in a single *file* that the reviewer can install with a
single "unzip" and access as a single set of specifications so
that we can manage this review cycle in an orderly way.

The only way that I (or anyone else in this conversation so far)
has been able to figure out how to accomplish this easily is to
roll both documents and all their supporting materials into a
single zip archive along with an html index that pretends to be a
document called the Review Package.  There are several advantages
to this approach.

 - The html index can easily be installed on our web site as a
   single web page containing pointers to all the subsidiary
   pieces.

 - The same index can be converted, using just a single
   search-and-replace operation, into the container for the whole
   standalone zip package.

 - The two major partitions of the html index can be labeled "Part
   1" and "Part 2" in a way that foreshadows their eventual
   publication as two separate documents.

 - The html index allows us to corral a whole zoo of disparate
   file formats (doc, pdf, xsd, xsl, xls, ...) into a single
   package that installs easily both on our web site and in the
   individual reviewer's hard drive and thereby gives us another
   three months in which to figure out how these things are
   actually going to be published as two printed documents.

 - This also allows us to leave the NDR document in exactly its
   current form -- a standalone printed document following the
   OASIS specification format that is simply pointed to from
   within the html index.  Pointing to this document from an html
   index shouldn't change its internal structure at all.

All of this assumes that we want both Part 1 and Part 2 to be
considered in parallel during the same review cycle.  This has
been my assumption for as long as we've been talking about this
review cycle.  If this is not our intention -- that is, if we want
two reviews on different schedules -- then of course most of what
I've been suggesting here doesn't apply.  If we want a single
review cycle -- which frankly is the only alternative that strikes
me as sane given the resources we have available to manage the
review -- then it seems to me logistically advisable to provide
all the pieces in one downloadable zip file.  For examples, see
the attachments to

   http://lists.oasis-open.org/archives/ubl-lcsc/200212/msg00066.html

Mechanically, this approach works very well.

However, Eve's comment above makes me realize that we probably
don't want to interject the "Intro," "Scope," "Definitions,"
etc. into Part 1 as I suggested earlier.  That really would screw
up the current organization of the NDR document.  So what I'm
suggesting now is that we leave the structure of the current
document formats (that is, the individual files) pretty much alone
and deal with figuring out editorial consistency as part of what
we (the chairs and editors) do during the three months that the
package is out for technical review.  Then the html index for the
review package would look something like this:

/=================================================================
| 
| H1 level: Review Package Title
| 
|    H2 level: Review Package Overview, including timeline,
|       contacts, mail lists, etc. (Tim or I can write this)
| 
|    H2 level: Universal Business Language Part 1: Naming and Design
|       Rules
| 
|       H3 level: Intro paragraph explaining the current role and
|          status of each of the subsidiary documents included in
|          this part of the package (Mark should write this)
| 
|       H3 level: Naming and Design Rules [pointer to .doc file]
| 
|       H3 level: Date and Time Representation [pointer to .doc
|          file] [perhaps, as Eve indicates, this piece should be
|          incorporated into the Naming and Design Rules file]
| 
|       H3 level: Code Lists (Informative[?]) [pointer to .pdf file]
| 
|       H3 level: Containership, Modeling, and Component Reuse
|          (Informative) [pointer to .doc file]
| 
|    H2 level: Universal Business Language Part 2: Library Content
| 
|       H3 level: Intro, Scope, etc.; Annexes (as previously
|          discussed)
| 
\=================================================================

Does this make sense to everyone?

Jon