MHonArc v2.5.0b2 -->
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.
-A
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)
>
>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.
>
>
>
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.
-------------------------------------------------------------------------
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.
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.
- 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?
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.
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?
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.
- 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 ...'?
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.
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.
-----------------------------------------------
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.
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?
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.
- 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 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.
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]