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