Re: Glossary comments from Quality Review

[Tim McGrath <tmcgrath@tedis.com.au>]

At the Vancouver plenary, the TA Team gave notice of their intention to
ask the Steering Committee to vote on the ebXML Glossary at its next meeting. 
Assuming this is the meeting of February 28th, the Quality Review team
would like to table its comments on this document.

The QR team have reviewed the Glossary from the perspective of both its structural integrity and its choice of attributed sources for definitions.  On these points our comments are:

structural integrity
a. clashes
    * The term "basic core component" and "basic information entity" appear synonymous, yet have different definitions and are both attributed to the same source.  why did we invent two terms?
    * The term "party" is defined but the term "partner" is not even though it is widely used in other terms.

b. inconsistency
    * many terms have no source specified, if these are ebXML definitions then either attribute them (as with "CC/Core component terminology"or "Message Service Specification") - at least make the reference to ebXML definitions consistent.
    * the defintions for the terms "identifier","unique identifier" and "UUID" need to be aligned.
    * the description section contains a mixture of description information, examples, synonyms, contrasting and/or related terms.  although an attempt has been made with some terms, these other attributes need to be maintained separately from the description.

c. gaps
    * the term "compile time" rates an entry (?) but the much abused "run time" does not.
    * several terms use either the term "enterprise" or "organisation" in their definition but neither term is defined.

d. redundant or superfluous definitions
    * do the terms "Deliverable" or "Diagram" need to be in this glossary?

e. the document needs a version and datestamp on it

sources for definitions
* 'schema' uses a localised definition and may be an overloaded term (some would assume its definition as per W3C XML)
* is "Rational Unified Process" the definitive source for the term "Object"?
* a source not matched with acronym (e.g. "open-edi" is "(MoU)" not "(MoU/MG)"
* sources should be identifiable (e.g. "what is UML Distilled and how do I find it?", "What is COD?")
 

However, the QR team do not see these issues as preventing us from recommending that this version of the ebXML Glossary (version 95??) be accepted by the Steering Committee.

Having made that recommendation, the QR team have some concerns about the quality of some definitions used here.

Many ebXML documents rely on the glossary (for examples they don’t include their own acronym or definition sections).  Whilst we do not presume to judge the validity of the Glossary terms and their definitions, when it comes to practical application of this Glossary there are many cases where:

a. the definitions appear out of context or too generalised to add any real value to understanding the use of the term within the technical specifications.  For an example of what we mean, see the definition for "Client", "Model" or "Argument".

or else

b. the definitions are too specific to parts of the ebXML framework.  For example "Date" relates only to this term's use within the core component specifications.

These weaknesses are commonplace and as such, jeopardise the value of this Glossary as a useful reference.  Therefore, we would ask the Steering Committee to task the Glossary team with addressing all of these issues before the next release of this document and suggest that revision be completed prior to the second round of review for the final ebXML specifications (ie March 19th).
.

--
regards
tim mcgrath
TEDIS   fremantle  western australia 6160
phone: +618 93352228  fax: +618 93352142