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)

Hi Jon,

As per my AI on Tuesday, I've reviewed most of this document build.   I 
must say, this is an amazing document!  It has a lot of information, and 
very well presented.  Here are some things I ran into for consideration 
for the final build.  I've looked at the main body, appendix A and just 
the start of appendix B.  Will try to get through the rest of appendix 
B, C and D tomorrow.


jon.bosak@sun.com wrote:

>The Easter Bunny has left this new build for you all:
>   http://ibiblio.org/bosak/ubl/UBL-1.0/
>He did the following this time:
>   Included new UBL-1.0-DevProcess.jpg from Tim McGrath and
>   changed link from gif to jpg
>   Included a heap of editorial changes from Tim McGrath, 
>   especially in Sections 5 and 6 and Appendix B
>   Included new UML implementation models from Dave Carlson
>   Made lots and lots of little editorial and cosmetic changes
>Items still missing:
>   doc/UBL-CL-1.0.pdf (Appendix E)
>   doc/UBL-CM-1.0.pdf (Appendix B.7)
>   doc/UBL-NDR-1.0.pdf (Appendix B.4)
>   doc/UBL-credits-1.0.pdf (Front matter)
>   Appendix C: Formatting Specifications (all)
>   Appendix G: RELAX NG Specification (all)
>   Appendix H: Future Work Items (all)
>   Links to pdf files for instances (see Appendix D)
>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.

Review of UBL 1.0 build document linked from email posted by Jon
to UBL list on April 11 at 5:35 pm.  These comments are made on
the downloaded .zip package obtained through that document link.



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


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

- Spreadsheets don't show document name in title - just 'UBL'.

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


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.

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.

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

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.

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

  + 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?

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?


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

- Specialised Datatypes section uses the term 'facets'
  ('... such as facets.'), so perhaps we need an XSD2 reference here?

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

6.2.3 Documentation Metadata Schema

- First sentence has 'in in' typo.

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

- and perhaps  '13' -> 'thirteen'

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?

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.

A.4 Tools

- This is a little vague, so if I can get you a better para before noon
  tomorrow I will.

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')

- Third para after figure B-1, 'Further' -> 'Additional', or 'Separate'

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

B.2 Component Model

- Second sentence, 'domponent' -> 'component'

- Second bullet above figure B-2 'It provides for understanding ...'
  -> 'It facilitates understanding ...'?


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

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.

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


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.

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

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?

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?

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

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 through  Lacking that higher
  level of detail, it is difficult to see how the information in sections thorugh 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.

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