[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [ubl] Partial UBL 1.0 build (11 April)
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]