Re: [ubl] Second UBL 1.0 Q/A build, take 2 (20 April)

[Anne Hendry <anne.hendry@sun.com>]

You're making us work awfully darn hard to find anything new!

I was only able to get through Appendix B by this time.
Attached are things that were either still open from before or new minor 
suggestions.
Really nothing that would be a showstopper.

-Anne

jon.bosak@sun.com wrote:

>To solve the page formatting problem noted earlier by Anne Hendry,
>I have fallen back on the insertion of simple manual page breaks.
>With a wee bit of editing (nothing substantive -- biggest change
>was to put the former A.1 at the end of Appendix A, which I had
>considered doing for organizational reasons anyway) I have come up
>with a version that will produce reasonable US and A4 printouts on
>Mozilla using the defaults and will produce equally reasonable US
>and A4 printouts under IE if the page margins are set to 0.5 inch
>instead of the default 0.75 inch.  I think this is probably as
>good as it gets from an HTML original.
>
>I have rebuilt the package with this new version and installed it
>in place of the one that I published a few hours ago.  You can
>tell it's the new one because it's labeled "Second Q/A build, Take
>2".  From the standpoint of text and link debugging, it should be
>identical.  The only actual error I caught was one remaining
>reference to the absent RNG materials, which has now been deleted.
>
>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.
>
>  
>



There are 7 comments from the last review that were indicated as under
consideration for change.  They are still open, so since I didn't know
what their disposition was, I've listed them below.  I don't think any
of these are showstoppers, although still some may be confusing.
Perhaps things we might want to keep on the list for 1.1,
if we don't change now.

A few more new comments (minor, though) at the end.


-------------------------------------------------------------------------------

[Anne's original comments preceded by bar, Jon's response preceded by 'Jon'.]

| - 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.

Jon: For Tim: Didn't we decide that these would be removed?

| - 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'.

Jon: I think we should have a definition, but I agree that this one
doesn't quite do it.  Tim?

|   + 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?

Jon: 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?

Anne (new): Only reason I keep stumbling over this is I try to trace
the flow between boxes and wonder if there's some significance to the
line type - does one type represent direct, the other indirect, or ?
If someone is actually trying to follow this, it does come up.

| 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.

Anne (new): The note at the bottom of 6.2.2 is great, and resolves
some of this, but still leaving the term 'Qualified Data Type' with
a capitalized 'Q' and saying it's defined in CCTS is wrong.  It is
not defined in CCTS, as Mark confirmed.  It may be in a future version
of CCTS, but we are pointing users at the current version, and they
will not find that term there.  They will only find 'Qualifier Term',
and other uses of the word qualifier/qualified but with a lower case
'q'.  Only 'Qualifier Term' appears in their 'Definition of Terms',
not 'Qualified Data Type' or 'Unqualified Data Type'.  So we shouldn't
say those terms are defined by CCTS.

Also, were we going to change occurrances of 'Data Type' to 'Datatype'?

| - 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.

Jon: I'm open to suggestions.

Anne (new): How about 'Core Component and Datatype Schemas', or just
  'Datatype Schemas', since the datatypess are build from the cc types?
  I'm not sure.  Are all these reusable?  If people were to reuse,
  wouldn't we want them to start with the higher level (UBL BIE) ones?

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

Jon: I've already got a related (though not so extensive) query about
this in to Tim.  Let's see what he comes up with.

Anne (new): Hasn't changed.


-----------------------------------------------------------------------


New (minor) suggestions:

- In several places in the document there are pointers to the individual
  SC pages.  If there is going to be some realigning of the TC work groups
  in HK, then perhaps we might be better off only pointing to the top
  level UBL TC page in this document.  It will be easy for people to
  see from there if there is an sc link that corresponds to what they're
  looking for.  It's just to keep from getting locked in to maintaining
  legacy pages on the site beyond the top level TC page.  Just a thought. 

- Regarding page breaks when printing, the manual breaks solved the
  halved figure problem.  However, we should investigate for the next
  release what can be done in markup to keep the diagram on one page,
  so as not to have to put in manual page breaks, since it seems the
  page length on my printer (using Mozilla) is a bit shorter than what
  you had so I have several instances of a single line on a page.

- Section B.4
  'The UBL Naming and Design Rules are the product of the OASIS UBL NDR
  Subcommittee' I think would be better to spell out the sc name, as
  this is the first time the SC is mentioned.  I know 'Naming and
  Design Rules' are mentioned before, but this is now referring to
  a body of people, rather than a document or concept.

- Also, in general, and this might just be my nit, but I think references
  to the subcommittees by abbreviation should not run the 'SC' into the sc
  name.  Eg. should be UBL NDR SC, or UBL LC SC, or even LC SC or NDR SC,
  not UBL NDRSC or UBL LCSC.  Even preferrably, NDR Subcommittee, or LC
  Subcommittee, since SC is not really an appropriate acronym for
  'subcommittee'.  Even better yet to spell them out, as there are not
  that many references to the subcommittee names in the doc.

- I did check NDR references (that they refer to the checklist) and those
  seem fine.

- Why is there Appendix A.1 'Availability'?  It repeats the information
  at the top of the file so that we are keeping this info in two places
  which can more easily get out of sync.  Readers wouldn't have reached this
  place in the file without already having the information in this section.

- Appendix F: two links ('OSS Nokalva' and 'ASN.1 Information Site') have

  '... tool from OSS Nokalva (www.oss.com) ...' and
  '... at the ASN.1 Information Site  (http://asn1.elibel.tm.fr) ...' 

  why list the URL in text after the link, since it's obvious from the link?
  If that is to be kept, then might want to add 'http://' to www.oss.com.

- Why is the .css file used by the cm file (oasis-wd.css) one level up?
  Since all other docs are in pdf, shouldn't the stylesheet just reside
  in the same dir as the cm doc?

- A.2 Package Structure

  'mod' directory description says 'UBL spreadsheet models; see Appendix B.3'.
  Appendix B.3 is titled 'Document Assembly Models'.  Seeing as the directory
  name was changed in a previous release from 'sss' to 'mod', I think it's
  best to use the word 'document' rather than 'spreadsheet' in the description.

  This is somewhat related to the comment on B.1 above.

- A.3 Tools

  Spell out 'Tools and Techniques Subcommittee'
  This is the first time this sc is referenced.
  It is referenced again in B.5, but there the name is spelled out in full.

- A.4 Support

  States that 'Inquiries regarding UBL may be posted to the public ubl-dev
  list ...', but this sounds like general inquiries, whereas the ubl-dev
  list was created as a forum for implementation discussions I thought,
  with more general inquiries going to ubl-comment or to the ubl tc.
  If this is true, then perhaps we can say something along the lines of
  'questions related to UBL implementation may be posted to ubl-dev'?

  Also, note that there is no link in the box on the top level UBL TC page
  to the ubl-dev archive, as there is for the ubl-comment archive, so just
  a note that we should get one up there.

  Lastly, the only posting to ubl-dev this month is a spam message.
  Is there any chance we can get that removed?  I think oasis can.

- B.1 The UBL Development Approach

  '... all re-used components were combined into a separate spreadsheet ...'
  Are there any components that are used in more than one document but don't
  appear in reusable?  I'm only asking because I seem to recall some rather
  lengthy discussions on this at various times during the past year.  If
  they are not all in there, perhaps we can explain why some may not be.

- B.1 para 3

  Break second sentence into two after '... UBL 1.0 procurement scenario'.
  Rest of comments on B.1 in two places above still apply.

- B.2 bullet 1

  '... reusable components — i.e., the things that are common ...'
  -> '... reusable components — information components that are common ...'

- B.3.1

  3rd para:

  'Columns define the metadata associated with each component type.'
  -> 'Columns represent the metadata associated with each component type.'

  'Many of the spreadsheet columns are determined by [CCTS] requirements.'
  -> 'Much of the metadata is specified by [CCTS].'?

  2nd para after B.5:

  'NOTE: The UBL document schemas are generated from these spreadsheet models.
   However, ...'

   I think you can remove the sentence above, leaving 'NOTE: The normative
   forms of the UBL documents ...'  The earlier sentence just obfuscates
   the point, really.  And, this statement more rightly belongs in Section 6.
   I looked there and there is one of the first two sentences:
   'They are the only normative representation of the UBL 1.0 document types
   and library components' which would lend itself to being highlighted as
   well.  (Even more reason to highlight this in the schema section than
   in this component model appendix.)

   The remaining statement (in B.3.1) I think is true not only for the UBL
   document schemas, but for all the UBL schemas (documents, datatypes,
   reusable, etc).

- B.3.4

  First para refers to 'Guidelines for the Customization of UBL 1.0 schemas'.
  This is not the exact title of the document, so perhaps better to reference
  this directly with a local reference - to the link to the document in B.7?

- B.5

  Second para: '... perform Q/A with them ...'?

  Maybe 'checked them for validity, or checked them against xyz ...'?
  It's a question, though - what were they checked against?



That's all for now.  I think a lot of this has been reviewed at this point
and it's truly getting more difficult (without spending days) to find real
problems.  And the writing is very clear and consistent.  Very well presented!