Re: [ubl] Partial UBL 1.0 build (11 April)

[Duane Nickull <dnickull@adobe.com>]

Eduardo et al:

Agree.  I believe that the general rule is that it is okay if it is 
editorial in nature (typos etc.) however common sense would dictate that 
even those should be sent to the list.  As an Editor of other specs, I 
know that it prevents you from getting the same comments sent in from 
twenty different people.

As far as change request of any technical nature, they must be on the 
list to preserve the transparency of the process.

Duane

Eduardo Gutentag wrote:

> A nit: asking comments to be sent directly to the editor of a document 
> bypasses
> the archives and can be considered a no-no. This is particularly true 
> of a final CD
> that will go out for review - please contact Karl Best and ask him 
> what the procedure
> is for comments during public review time. It used to be to send 
> comments to the
> comments list, but I believe this may have changed. I'm not sure, though.
>
> On 04/15/2004 01:01 PM, Jon.Bosak@Sun.COM wrote:
>
>> I took Anne's review first because I suspected it would require
>> the most work.  :-)
>>
>> Tim McGrath and Stephen Green: note actions/queries attached to
>> your names in what follows.
>>
>> [anne.hendry@sun.com:]
>>
>> | Schemas
>> | -------
>> | | - In UBL-CommonBasicComponents-1.0.xsd, the 'Document Type' field 
>> of the
>> |   header comment block says 'CommonAggregateComponents' rather than
>> |   CommonBasicComponents.  This is probably going to confuse some 
>> folks.
>>
>> Logged in a list of schema changes I'm holding.
>>
>> | Spreadsheets
>> | ------------
>> | | - The spreadsheets contain a second sheet with the TBG 17 
>> information.
>> |   Should those be explained somewhere?  I haven't looked throroughly
>> |   through the appendices, but didn't see anything in a quick glance.
>>
>> For Tim: Didn't we decide that these would be removed?
>>
>> | - Spreadsheets don't show document name in title - just 'UBL'.
>>
>> The title does appear in the xls but not the sxc, so apparently
>> it's a conversion problem.  The title is captured in "headers and
>> footers," so it's in the sxc somewhere.  If there's time after doing
>> the other spreadsheet changes, we might want to fix this by hand.
>>
>> | - We've lost the little pop-up text on the first row of each color 
>> of the models
>> |   that explained what the colors mean.  If it's too late to put 
>> these back,
>> |   perhaps we can add something to the document section for those 
>> with this info?
>>
>> There is an explanation of the colors at the top of this section
>> (B.3.2).
>>
>> | Document
>> | --------
>> | | 2. Normative References
>> | | - For the UML reference, the first link points to the OMG site 
>> which yields
>> |   a document labeled as 02/07/07, Version 1.3.  However, the link 
>> to our
>> |   OASIS archived version yields a document from March '03, version 
>> 1.5.
>> | |   Since the reference in our doc identifies the links as being to 
>> 1.3, the
>> |   link to the oasis archived version should probably point to a 1.3 
>> version.
>>
>> Thanks for catching this; I forgot to ask.  The problem is that I
>> can't find the document for 1.3; the thing at the end of the OMG
>> link is just the XMI DTD.  The 1.5 document was the earliest I
>> could find.  Can someone find me a link to 1.3?  Alternatively,
>> should we point to 1.5?  The 1.5 spec lives at
>>
>>    http://www.omg.org/docs/formal/03-03-01.pdf
>>
>> (Pending an answer, I'm changing the link in the master doc to
>> point to the link above and the reference to 1.5.  I'll change
>> this back if anyone can find me 1.3.)
>>
>> | 3. Terms and Definitions
>> | | - In the def for 'Document', the example, 'placing an order', 
>> isn't really
>> |   appropriate to the term.  The more appropriate example would be 
>> 'an order
>> |   document used when placing an order', rather than 'placing an 
>> order' since
>> |   the term being described is the document, not the act of placing 
>> the order.
>>
>> I've added "in" before "placing an order."
>>
>> | - In the def for 'Functional Dependency', not sure how this came 
>> about,
>> |   but a 'Functional Dependency' is not a 'means of aggregating 
>> components'.
>> |   I'm not sure we need to have a def for 'functional dependency'.  
>> It's used
>> |   twice: B2. Component Model, first para, and in the def for 
>> 'Normalization'.
>>
>> I think we should have a definition, but I agree that this one
>> doesn't quite do it.  Tim?
>>
>> | 4. Symbols and Abbreviations
>> | | - For ISO, 'Organisation' is spelled with a 's', while 
>> 'Standardization'
>> |   is spelled with a 'z'.  On the ISO site they spell their name with a
>> |   'z' for both.
>>
>> Got it.
>>
>> | 5.0 UBL Procurement Process
>> | | - Second para uses the term 'document types' and last sentence 
>> refers to
>> |   these as 'businesses processes' ('It is expected that other standard
>> |   business processes will be added ...')  I think this should be 
>> 'document
>> |   types ...' or 'document types to support additional business 
>> processes...'.
>>
>> Actually, they don't refer to the same thing, but I agree that
>> the para would benefit from the first suggested change.  So made.
>>                                        
>> | - Figure 1:
>> | |   + Not clear at this point that the bolded boxes are the docs 
>> provided by
>> |     UBL 1.0.  This could be clarified by changing the word 'needed' 
>> in the
>> |     preceding sentence to 'provided by UBL 1.0', and/or add a label 
>> for
>> |     them in the diagram, as there is for the other diagram components.
>>
>> The para above the list now reads as follows:
>>
>>   <p>This model describes a basic trading cycle from Order to
>>     Invoice that involves three parties: a Buyer of goods, a
>>     Seller of goods, and a Recipient of goods, who may or may
>>     not be the Buyer. The document types provided by UBL to
>>     support this process include the following:</p>
>>
>> And the para just above the diagram now says:
>>
>>   <p>The bold boxes in the diagram below show the role of each
>>     document type in the generic process.</p>
>>
>> |   + The intro paras say that the Buyer may or may not be the 
>> Recipient.
>> |     However, the diagram only shows the situation where the Buyer 
>> is not
>> |     the Recipient.  The statement preceding the figure says this 
>> shows a
>> |     'generic' process, but since it only shows the generic process 
>> where
>> |     the Buyer is not the Recipient, I think it would be appropriate to
>> |     add the words 'where the Buyer is not the Recipient', or something
>> |     to that effect here, because the arrows would definitely be 
>> different
>> |     if the example was of a situation where the Buyer was the 
>> Recipient.
>>
>> I don't think that anyone is going to misunderstand this.
>>
>> |   + What is the diff in meaning between a dotted line and a solid 
>> line?
>> |     Can something be mentioned here to explain?  Or is this 
>> standard UML?
>>
>> Good question.  I came to the conclusion that the dashed lines
>> indicate a document exchange and the solid lines indicate a
>> process arc, but I don't know the UML nomenclature for this.  I
>> don't think that anyone will actually have a big problem with
>> this, but it would be good to get a sentence explaining the
>> distinction correctly.  Tim/Stephen?
>>
>> | 5.2 Document Business Rules
>> | | - Did not check the info in this section against the actual 
>> document models.
>> |   Does this still need to be done?
>>
>> I'm taking this on faith from the content modelers.
>>
>> | 6.2.2
>> | | - The use of both the terms 'specialised' and 'uspecialised' and
>> |   'qualified' and 'unqualified' is extremely confusing here.
>> |   I did a search through ccts, and could not find either the term
>> |   'Qualified Data Type' nor the term 'Unqualified Data Type'. |   
>> The Unspecialised Datatype section says this term is 'specified'
>> |   by ccts; the Specialised Datatype section says this term is 'defined
>> |   in CCTS'.  However, as I mentioned, I couldn't find the term in 
>> ccts,
>> |   so I think the accuracy of these statements should be checked.
>> | |   CCTS does talk about a 'Qualifier Term', which is defined as a 
>> word
>> |   or name (uncapitalized).  Therefore, uncapitalizing 'qualified' or
>> |   'unqualified' would at least help keep that term from conflicting
>> |   as much with the use of the term 'specialised' in the names, but
>> |   explaining a bit more what is meant would also help, since people
>> |   are going to go to the referenced CCTS and not find these terms 
>> there.
>>
>> Tim?
>>
>> | - Specialised Datatypes section uses the term 'facets'
>> |   ('... such as facets.'), so perhaps we need an XSD2 reference here?
>>
>> I don't think so.  The whole thing assumes some familiarity with
>> XSD terminology.
>>
>> | - Naming the 3 ccts-conformance schemas 'Reusable Datatype Schemas'
>> |   doesn't jibe with the description at the top of the section, and
>> |   I think will have people confused with the 'Reusable BIE Schemas'.
>> |   The description at the top also doesn't clarify if these are to
>> |   be reused at the document level, so people might expect this, as
>> |   with the other 'reusables' if the distinction is not clear.
>>
>> I'm open to suggestions.
>>
>> | 6.2.3 Documentation Metadata Schema
>> | | - First sentence has 'in in' typo.
>>
>> Got it.
>>
>> | 6.3 UBL Code List Schemas
>> | | - Either change 'The 13 code lists ...' to 'The 13 code list 
>> schemas ...'
>> |   or change '... are included in the xsd/codelist directory.' to
>> |   '... are included in the schemas in the xsd/codelist directory.'
>>
>> I'll take the former; done.
>>
>> | - and perhaps  '13' -> 'thirteen'
>>
>> I ordinarily follow the Associated Press rule (everything below 10
>> is spelled out), but it does look strange here.  On checking the
>> Chicago Manual of Style, I see that their rule is to spell out
>> everything below 100 except for certain specific exceptions, so I
>> think that's what we'll do here.  Change made, and I'll try to
>> look for similar cases in another read-through.
>>
>> | 6.4 Schema Dependencies
>> | | - Figure 2 shows '<< import >>' for all the schemas except the CCP.
>> |   Shouldn't the lines going into this module show an << import >>
>> |   as well?
>>
>> Tim?
>>
>> Appendix A
>>
>> | A.3 Package Structure
>> | | - Second sentence.  Stop sentence at '... 1.0 release', delete 
>> rest of
>> |   sentence and replace with 'After uncompressing the zip archive you
>> |   should see the following directories and files'.  Then list all the
>> |   directories and files that will be at the top level.  People want
>> |   to know exactly what they should see after the unzip, so listing
>> |   the files at the top level (either before or after the 
>> subdirectories)
>> |   is important too.  Since the archive should be contained within a 
>> subdir
>> |   itself, this also would be shown.
>>
>> I want to keep the subdirectory list the way it is so that
>> truncated references such as "art/" stay consistent thoughout the
>> document.  So I've changed the intro para to read as follows:
>>
>>   <p>The UBL 1.0 specification is published as a zip archive named
>>     UBL-1.0.zip.  Unzipping this archive creates a directory named
>>     UBL-1.0 containing a master hypertext document (this
>>     document, index.html) and a number of subdirectories. The
>>     files in these subdirectories, linked to from index.html,
>>     contain the various normative and informational pieces of
>>     the 1.0 release.  A description of each subdirectory is
>>     given below.</p>
>>
>> | A.4 Tools
>> | | - This is a little vague, so if I can get you a better para 
>> before noon
>> |   tomorrow I will.
>>
>> I want it to be a little vague.  Our way of handling the other end
>> of this reference may undergo a lot of changes over the life of
>> the 1.0 spec.
>>
>> | Appendix B
>> | | B.1 The UBL Development Approach
>> | | - Second para after figure B-1 describes two models:
>> |     document component model and document assembly model(s)
>> |   Following 2 paras should use same terminology:
>> |   + 'component model' -> 'document component model'
>> |   + 'spreadsheet assembly model(s)' -> 'document assembly model(s)'
>> |                         (or 'document assembly model spreadsheets')
>>
>> I've already got a related (though not so extensive) query about
>> this in to Tim.  Let's see what he comes up with.
>>
>> | - Third para after figure B-1, 'Further' -> 'Additional', or 
>> 'Separate'
>>
>> I'll take "additional."
>>
>> | - Fourth para after figure B-1 talks about 'implementation models',
>> |   but only conceptual models had been discussed so far.  Maybe just
>> |   put this as a new para, then?
>>
>> I think this is OK for a brief overview of the sections that
>> immediately follow.
>>
>> | B.2 Component Model
>> | | - Second sentence, 'domponent' -> 'component'
>>
>> Got it.
>>
>> | - Second bullet above figure B-2 'It provides for understanding ...'
>> |   -> 'It facilitates understanding ...'?
>>
>> I've gone for "aids in understanding."
>>
>> | B.3.1
>> | | - I just checked briefly the SS error Stephen described in his 
>> review,
>> |   but I don't see it - they open just fine on my Windows 2000 system
>> |   (both .xsc and .xls).  I'm using OO, though.
>>
>> I'll look at this separately.
>>
>> | Misc
>> | | - I'm sure this is noted somewhere already, but the NDR 
>> references need
>> |   to be checked at the end depending on what actually gets included 
>> with
>> |   the release.
>>
>> We'll have to try to remember this.
>>
>> | -----------------------------------------------
>> | Misc and/or Lower Priority (if time constrains)
>> | -----------------------------------------------
>> | | When I print this out I get many diagrams spread across a couple 
>> of pages
>> | (truncated at the end of one page, continuing on the next).  Can 
>> diagrams
>> | be kept from crossing page boundaries by adding something to the 
>> document
>> | markup?  I printed them using the html file in the build.
>>
>> Thanks -- I hadn't tried printing yet.  I don't know any way
>> around this problem, but maybe there's something in CSS that can
>> be used to put in a conditional page break (I'm using CSS 1 to try
>> for maximum browser interoperability, but if I get a chance before
>> we put out the final build, I'll try to look into this further and
>> maybe even check out CSS 2).  Note that hard-coding some kind of
>> cruft like empty paras won't work because of different page
>> formats (US vs. A4), user-settable font sizes, optional
>> headers/footers, different browsers, and similar variables beyond
>> our control.
>>
>> | Abstract: add 1.0?  Generally refer to this release with the 1.0 added
>> |   where the mention is specific to this release?  There are some very
>> |   generic paras at the beginning where this would not be appropriate,
>> |   but otherwise it seems it would be.
>>
>> I added "1.0" in one spot (probably the one that made you think of
>> this), but otherwise I think the other references to UBL should
>> stay generic.
>>
>> | Schemas
>> | -------
>> | | - I still think it's quite confusing to have the Reusable model 
>> come out
>> |   as two schemas (CAC and CBC).  Could we update this in 1.1 or 2.0?
>>
>> Not a Q/A issue at this point.  We can fight about this later.
>>
>> | Document
>> | --------
>> | | 1. Introduction
>> | | - Throughout first couple of paras and first four bullets there 
>> is use of
>> |   the term 'version', as in 'XML versions', and use of the term 
>> 'formats',
>> |   as in 'XML formats' or 'data formats' and these are used 
>> interchangeably.
>> |   Since it appears these are both talking about the same thing, it 
>> would
>> |   help the reader if only one of these terms is used consistently 
>> throughout.
>>
>> They don't mean exactly the same thing, and I think that
>> collapsing the distinction would not aid readability.
>>
>> | - The first page or so of the Intro explains the context for UBL, 
>> basically
>> |   setting the stage.  Then para beginning 'UBL schemas are modular 
>> ...' goes
>> |   into the details of this particular UBL release.  It would be 
>> helpful to
>> |   here either have a new subheading, or at least begin putting 
>> '1.0' in
>> |   front of the UBL references, since the earlier sections could be 
>> applied
>> |   to any UBL release, whereas the text starting with this para 
>> seems to be
>> |   more specifically about this particular release and it's contents
>> |   (UML diagrams, etc).
>>
>> The predicates "modular, reusable, and extensible" apply to UBL in
>> general.  I see your point about the rest of the para, but most of
>> this applies to all contemplated versions of UBL, and I'd rather
>> leave it the way it is.
>>
>> | 5.0 UBL Procurement Process
>> | |   + The flow (arrow directions) for Cancel Order are a bit strange.
>> |     If you follow Cancel Order from the Buyer side, when it gets to 
>> the
>> |     Seller side it runs into several arrows coming in the other 
>> direction
>> |     from 'Accept Order' and 'Add Detail'.  It seems they should go 
>> on to
>> |     an end point, but there are no arrows coming out of Cancel 
>> Order on
>> |     the Seller side, only those two arrows going in.  In other words,
>> |     you can't follow the arrows for the Cancel Order process to any
>> |     logical termination point, as you can for the others.  The 
>> description
>> |     (5.2.5) seems to indicate that Cancellation can be initiated 
>> only by
>> |     the Buyer, so the description doesn't really support the other 
>> arrows
>> |     (from Seller Accept Order and Seller Add Detail).
>> | |   + On the Buyer side, there is an arrow from Recieve Response to
>> |     Recieve Advice.  But it doesn't seem to me that a Buyer would go
>> |     from receiving an Order Response straight into a Receive Advice 
>> state
>> |     without getting a DespatchAdvice first.  It would seem that this
>> |     would need to be triggered by a Despatch Advice.  If so, then I 
>> don't
>> |     think there should be an arrow from Receive Response to Receive 
>> Advice.
>> |     I think it might be there because that is the logical next step 
>> for
>> |     the Buyer, but it occurs not directly, but indirectly, after some
>> |     period of time has elapsed and a DespatchAdvice comes in, I 
>> would think.
>> | |   + There are some other things, but this might take some time to 
>> work
>> |     through.  Perhaps this could be a 1.1 work item (to review this
>> |     section) and expand on it as per the general comment for 5.2, 
>> below?
>>
>> Unless someone in LC wants to make a change at this point, I
>> think we should hold further refinements for 1.1.
>>
>> | 5.2 Document Business Rules
>> | | - Generally, the information in this section touches on some 
>> specific
>> |   mini-scenarios that could be handled by each of the documents, 
>> but not
>> |   in a way that could be easily related back to, or sufficiently 
>> covers,
>> |   the available entities - there is still a lack of information 
>> pertaining
>> |   sepcifically to how a user would use each of the entities of each 
>> of the
>> |   documents.  Customers have asked for this and we've discussed it 
>> in the
>> |   ISC - that we need some tutorial type information, or a handbook or
>> |   something that has more information than we have available here.
>> |   A 1.1 item?
>>
>> Yes, I think so.
>>
>> | - First sentence "This section describes the business rules ... 
>> that are
>> |   assumed as information requirements ...".  I'm not sure what the 
>> thought
>> |   is that is being expressed there, but the following sections 
>> don't so
>> |   much describe business rules as they describe the capabilities of 
>> the
>> |   document types and the information that they can exchange, so 
>> perhaps
>> |   the statement would be clearer if 'business rules' was changed to
>> |   'business information requirements' and then drop
>> |   'that are assumed as information requirements' later in the 
>> sentence.?
>> |   Along these lines, I think the title is a misnomer as well, since 
>> the
>> |   section really doesn't describe business rules as much as the 
>> business
>> |   entity capabilities and document usage (rather than rules).
>>
>> I think that the section does in fact convey a lot of information
>> about business rules.  It could be better, but from a logistical
>> standpoint I would put this into category of further work.
>>
>> | 5.3 Item Business Rules
>> | | - Again, this doesn't seem to specify rules as much as best 
>> practices,
>> |   it seems.
>> | | - This may be clear to others, but at the start of 5.3.1 there is 
>> a list
>> |   of the 5 ways an Item may be identified.  It would be most 
>> helpful to
>> |   have those described here before diving into the next level of 
>> detail
>> |   given by subsections 5.3.1.1 through 5.3.1.3.  Lacking that higher
>> |   level of detail, it is difficult to see how the information in 
>> sections
>> |   5.3.1.1 thorugh 5.3.1.3 relate back to the type of items 
>> identified in
>> |   5.3.1 and how to use that information.
>> | | - Also, the first sentence of this section says 'Item structures 
>> are found
>> |   throughout the document types ...', but when you look at the 
>> document
>> |   models, 'Item' is not at all obvious - it's hidden in the other 
>> structures
>> |   so you really don't see what's being discussed unless you look at 
>> Reusable.
>> |   So it may help to give a pointer here to Reusable (or perhaps 
>> move this
>> |   section to after the discussion of the Reusable/common components),
>> |   or simply to say 'document instances', rather than 'document types',
>> |   as Item is very obvious in the instances.
>>
>> Same here.
>>
>> Jon
>>
>> To unsubscribe from this mailing list (and be removed from the roster 
>> of the OASIS TC), go to 
>> http://www.oasis-open.org/apps/org/workgroup/ubl/members/leave_workgroup.php. 
>>
>>
>

-- 
Senior Standards Strategist
Adobe Systems, Inc.
http://www.adobe.com