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

[jon.bosak@sun.com]

[anne.hendry@sun.com:]

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

No answer; we'll have to go with what we've got.

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

No answer; we'll have to go with what we've got.

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

No answer; we'll have to go with what we've got.

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

I've removed the reference to CCTS.

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

I was under the impression that we were reflecting CCTS here.  Too
late to try to impose order this time around.

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

Too late to change now.

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

We'll have to go with what we've got.

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

I considered this but came to the conclusion that there's so much
stuff stored in each SC tree that we will have to keep them the
way they are for future reference even if we decide to retire
them.

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

I actually just "printed" all the tests to PDF and proofed them
that way.  People can get around this by adding a skosh of extra
space to the top or bottom margin (which they will have to do
anyway in IE).  I don't know of any way in CSS to keep a diagram
on one page; if anyone does, let me know.

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

I don't think anyone's going to be confused about it in this context.

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

This is a flip-the-coin decision.  The current document
consistently represents the acronyms without a space to align with
the way they appear in the kavi URLs.

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

It's presented here as a lead-in to A.2.  You're right about the
duplication, though.  I'll revise this to just point back to the
top of the document.

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

All links are spelled out so that they appear in printouts.

|   If that is to be kept, then might want to add 'http://' to www.oss.com.

Done.

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

Done.

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

Too late to change this now.

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

Done.

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

No, ubl-dev is the only list we have for public discussions of any
kind.  OASIS now limits the comment list to a forms-driven
interface for comments only.

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

An excellent point.  Help me remember this when I update the TC
page next week.

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

I'm not going to spend time on this.  There's at least one such
message in the ubl list, too.

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

Too late.  Take this up with Tim.

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

I can't second-guess the description of the process at this point.

| - B.2 bullet 1
| 
|   '... reusable components — i.e., the things that are common ...'
|   -> '... reusable components — information components that are common ...'

Yeah, I don't like "things" here either.  I think that a change to
"data structures" should be safe enough.

| - B.3.1
| 
|   3rd para:
| 
|   'Columns define the metadata associated with each component type.'
|   -> 'Columns represent the metadata associated with each component type.'

I think you're right, but someone might argue that "define" is
intended here.

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

That might be substantive; too late.

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

I think this is OK the way it is.

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

I'll just lowercase "guidelines" and "customization" in this place.

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

Got me; I'm just putting together language provided by others (in
this case, Sylvia).

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

Credit goes to everyone who contributed the language.  I agree
that we've probably reached the point of diminishing returns for
this release.

Jon