[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 email@example.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 126.96.36.199 through 188.8.131.52. Lacking that higher level of detail, it is difficult to see how the information in sections 184.108.40.206 thorugh 220.127.116.11 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]