Preliminary edit of UBL 2.1 PRD3 Common Library spreadsheet for definition review

[Jon Bosak <bosak@pinax.com>]

Hello UBL 2.1 content providers,

Many of you will recall my editorial review of the definitions in the
UBL 2.1 PRD3 document models:

https://lists.oasis-open.org/archives/ubl-psc/201206/msg00001.html
https://lists.oasis-open.org/archives/ubl-tsc/201206/msg00001.html

I have just finally completed an initial editorial review of the
definitions in the UBL 2.1 Common Library, and we can now begin to move
this task toward completion.  You can get the review version of the
Common Library spreadsheet at

https://www.oasis-open.org/apps/org/workgroup/ubl/download.php/46900

Note that there are three files in this zip archive: an OpenOffice
version, an Excel version (which for technical reasons is the one that I
actually used for the review), and a PDF file containing a printout that
I hope will work for people doing an initial read-through on paper.
More about all this below, but note that the spreadsheet exists only
for purposes of this review and is not a replacement for the version
maintained in eDoCreator.

I will begin with some background to the approach taken to the
definition edits, and then give instructions for how I would like the
subcommittee and stakeholder review to take place.

Before I get to that, however, I want to emphasize the absolute need for
a careful review by the teams that provided the 2.1 data models in the
first place.  You will find many places where questions have been posed
that must be answered before we can continue, and obviously these will
require close attention from the only people who can provide definitive
answers to those questions; but nearly all of the definitions had to be
modified in one way or another in order to regularize the language, and
EVERY modification carries with it the risk that I have misunderstood
the original definition in making the change.  Thus, it is imperative
that everyone involved in design of the models carefully review ALL of
the revised definitions, not just the ones that I've flagged with
specific questions.

Now onward to some background explanation.

1. Approach to the definitions

Here is an initial statement of the new approach I've taken in wording
the definitions.  I intend for some version of this to eventually end up
in the hubdoc, probably in Appendix A.  (No need to review this right
now; it will be part of the overall document review.  I'm including it
here only by way of explanation.)

/============================================================================
|
| A Note Regarding the Definitions
|
| [The example used in the following will need to be revisited when
| final language is decided on for taxtotal.]
|
| Since the definitions for each of the 4000+ uniquely named data items
| in UBL 2.1 are normative, it is important that each be specified with
| the greatest care possible.  However, there are two very different
| approaches that can be taken in accomplishing this objective.
|
| One approach, used more or less by default in UBL 2.0, is to give a
| definition for each item that correctly describes that item as a node
| in a data model.  This is the approach that resulted in (for example)
| the UBL 2.0 definition of TaxTotal in CreditNoteLine as "An
| association to Tax Total".  While perfectly correct from the
| standpoint of data model construction (the ASBIE for TaxTotal is, in
| fact, an association to the class or ABIE named Tax Total), such a
| definition is less than ideally useful for the business analyst
| attempting to determine the meaning of "TaxTotal" as an element name
| in an actual Credit Note.  The definition of the ASBIE could, of
| course, have been extended through to the definition of the ABIE Tax
| Total, which in UBL 2.0 is "Information about a total amount of a
| particular tax", but even here an attempt to be absolutely correct
| can lead to a pathological expansion, as "Information about a total
| amount of a particular tax" becomes "A description of information
| about a total amount of a particular tax" and then "Structured data
| constituting a description of information about a total amount of a
| particular tax" and so on.
|
| The second approach, taken here in UBL 2.1, is to write each
| definition as an answer to the question "What does this mean?" in the
| context of an actual document instance containing the item.  Thus, in
| UBL 2.1, the definition of TaxTotal in CreditNoteLine has changed
| from "An association to Tax Total" to "A total amount of taxes of a
| particular kind applicable to this credit note line."  This
| compression of levels of abstraction has been carried through so far
| as to eliminate phrases such as "A description of" in the great
| majority of cases, leaving it to the reader's common sense to
| understand that a definition such as "The delivery requested by the
| party requesting a transportation service" refers to a description of
| the act of delivery and not the physical delivery itself, which of
| course could never literally be part of a document.  The only
| widespread exceptions to this policy are the definitions of ABIEs in
| the Common Library, which begin "A class to describe..." or sometimes
| "A class to define..." in order to emphasize their more abstract
| role.  The designers of UBL 2.1 believe that anything lost in
| technical correctness through this approach will be more than
| compensated for in improved practical usability.
|
\============================================================================

I didn't add this in the explanation for the user, but you should
understand in considering the edited definitions that I've taken an
approach known in documentation and usability circles as "controlled
vocabulary," which means that every attempt has been made to use as few
different words as possible by employing a small library of set phrases
for similar concepts.  This reduces the amount of English required to
understand the definitions and greatly aids in translation.

2. The Review Spreadsheet

Take a look at the spreadsheet (either .xls or .ods) and you will see
that it has been rearranged for purposes of this review.  Many columns
in the actual eDoCreator version have simply been omitted, and several
new ones added.  From left to right, they are:

   Column A: UBL Name

      From the original spreadsheet.  A red background indicates a place
      where a change needs to be made to a name (e.g., "Criterion" for
      "Criteria", or to correct a misspelling).  In such cases, the
      revised name is given in column K, "Corrected UBL Name (assumed)".

   Column B: Dictionary Entry Name

      From the original spreadsheet.  A red background indicates a place
      where a change needs to be made to a name (e.g., "Criterion" for
      "Criteria", or to correct a misspelling).  In such cases, the
      revised DEN is given in column L, "Corrected Dictionary Entry
      Name".

   Column C: Definition

      From the original spreadsheet.

   Column D: New Definition

      My rewritten definition based on what I THINK the original
      definition meant.  Always requires at least a glance from a person
      knowledgeable about the originating project.

      Empty cells in this column indicate that the original definition
      needed no change.  Places where I could not come up with a final
      edited version are (or should be) indicated with a question mark
      (?).

   Column E: Associated Object Class

      From the original spreadsheet.

   Column F: Cardinality

      From the original spreadsheet.

   Column G: Component Type

      From the original spreadsheet.

   Column H: Query

      A question or comment from me.  Requires a response from a person
      knowledgeable about the originating project.  Note that "Cf." in
      these queries means "Compare".

   Column I: Response

      The required response from a person knowledgeable about the
      originating project.

   Column J: Revised Definition Proposed by Reviewer

      A place to record a version the reviewer believes to be correct,
      if different from the New Definition (if that exists) or the old
      Definition (if no New Definition is provided).  In the case where
      a question mark (?) has been written into the New Definition
      column, the expert respondent is expected to provide a correctly
      revised new definition in the "Revised Definition Proposed by
      Reviewer" column.

   Column K: Corrected UBL Name (assumed)

      and

   Column L: Corrected Dictionary Entry Name

      I'll take these in reverse order.  The "Corrected Dictionary Entry
      Name" column records places where a change to the original DEN has
      been found necessary (e.g., "Criterion" for "Criteria").  Such
      changes will need to be made in eDoCreator.  These cells have a
      red background to signal special attention.  The corresponding
      entry in the "Corrected UBL Name (assumed)" column is what I'm
      assuming will be generated from the corrected DEN.

Note that for readability, columns E, G, J, K, and L are omitted from
the PDF containing the print version in the package linked above.

REVIEW PROCESS

Here's an outline of the process I'd now like us to follow.  Details
will need to be worked out at the subcommittee level.

1. PSC and TSC assign responsibility for each ABIE and its children to
   an expert associated with the originating project.

2. The expert reviews each New Definition (column D) and provides a
   response in column I for each query or comment in column H.  If
   responding to a question mark (?) in column H, or if improved wording
   occurs to the reviewer, it is expected that a revised and corrected
   new definition will be provided in column J.

3. Subcommittee chairs provide the input in an organized way back to the
   TC level for further action.

NOTE REGARDING FINAL AUTHORITY

As has been the case since this project began, the judgement of the
content providers will almost always be taken as final.  If mistaken, my
comments, questions, or wrongly conceived new definitions should not be
taken as indicating more than a failure of understanding on my part;
just correct things and move on.  But please do remember that a failure
of understanding on my part represents a failure of understanding on the
part of many future users and indicates the need for some revision, even
if it's not the kind I've provided.