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