OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

ubl message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


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.
> 

-- 
Eduardo Gutentag               |         e-mail: eduardo.gutentag@Sun.COM
Web Technologies and Standards |         Phone:  +1 510 550 4616 x31442
Sun Microsystems Inc.          |         W3C AC Rep / OASIS BoD


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]