Examples and descriptions

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

Hello UBL TSC,

Something caught my eye today that might be representative of a 
recurring documentation issue that does not impact on the schema constraints.

Looking at row 898 of the common library as it exists today in the 
data model, the "Goods Item. Preference Criterion Code. Code" element 
has what reads as a description under the example.  I believe the 
example is supposed to only illustrate sample values and not provide 
descriptive information, even if it is about those sample values:

  Description:  A code specifying the treatment preference for this
                good according to international trading agreements.

  Example:  Preference Criterion is used in the following manner in
            the paper CO of another country (e.g.):A - The good is
            wholly obtained or produced entirely in the territory of
            one or more of the NAFTA countries as reference in
            Article 415. Note: The purchase of a good in the
            territory does not necessarily render it wholly obtained
            or produced . If the good is an agricultural good, see
            also criterion F and Annex 703.2. (Reference: Article
            401(a), 415).B - ...C - ...D - ...E - ...F - The good is
            an originating agricultural good under preference
            criterion A,B, or C above and is not subjected to
            quantitative restriction in the importing NAFTA country
            because....Thus, the column Preference Criterion will
            indicate either A, B, C,...

I grant that this is useful information ... I only question it 
showing up under "Example".  Would it be better placed in the 
description?  Would it be better placed in supplementary material?

Other descriptions are written not to be tutorial in nature, but descriptive.

I do not know if there are other examples of such improperly-written 
examples ... this one just caught my attention.

I hope this helps.

. . . . . . . . . . Ken

--
Public XSLT, XSL-FO, UBL and code list classes in Europe -- May 2012
Contact us for world-wide XML consulting and instructor-led training
Free 5-hour lecture: http://www.CraneSoftwrights.com/links/udemy.htm
Crane Softwrights Ltd.            http://www.CraneSoftwrights.com/o/
G. Ken Holman                   mailto:gkholman@CraneSoftwrights.com
Google+ profile: https://plus.google.com/116832879756988317389/about
Legal business disclaimers:    http://www.CraneSoftwrights.com/legal