Re: Membership and Public Review of OASIS Artifact Standard Identification Scheme for Metadata

[Norman Walsh <ndw@nwalsh.com>]

First, let me say that the document seems much improved from previous
versions. My congratulations to the editors and authors. However, I
don't think the document is ready for adoption. There are simply far
to many places where it's unclear or underspecified.

At a very high level, I have five comments, in no particular order:

* It's incomplete. There are many sections that simply don't describe
  the intent of the specification in adequate detail. I don't mean
  that as a criticism of the authors or the editors, it's simply a
  document that's still in a draft state.

* Mandatory metadata in the documents, especially in specifications,
  is a great idea. In fact, I think it should be made even more
  explicit right down to how the metadata is formatted in the
  normative XHTML. But the whole scheme for artifact names seems
  overly complicated and brittle.

  If exampletc publishes V1.0 of a product specification in

     http://docs.oasis-open.org/exampletc/product/v1.0/

  does it really matter how the individual artifacts at the end of
  that path are named? Changing the names of all the stylesheets and
  schemas and included modules, etc., every time the spec is revised
  may have a significant cost in terms of development time.

* The draft specifies two normative formats. I remain of the opinion
  that this is an unacceptable state of affairs.

* The TC Administrator is involved all over the place. Please provide
  a concise summary, in an appendix, for example, of all the choices
  that must be reviewed by the administrator.

* I think the document would benefit greatly from many, many more examples.
  Especially complete examples of multiple products, with multiple versions,
  in multiple languages, that have multiple schemas, and other ancillary
  files.

In more detail:

Line 216 introduces the possibility that the TC Administrator might
         create aliases for some or all existing artifacts.

  Please don't[1].

Line 230 introduces "Artifact Identifier" which is also a name for
         an Artifact.

Line 234 introduces "Artifact Name"

Line 237 introduces "Filename"

Line 290 introduces "OASIS Defined Name"

  Are all four of these terms necessary? If they are, the document
  does not sufficiently distinguish between them.

Line 263 abbreviates "requirements"; line 265 abbreviates "specification".

  Please don't. The few characters saved pale in comparison to the
  confusion caused by abbreviations, not only for non-English
  speakers, but also for those of us who have to remember,
  "'requirement' is abbreviated, but 'profile' isn't, is that right?
  Or is it the other way around?"

Line 271 places a burden on the TC and the TC adminstrator for any
         novel artifact type.

  That really seems unneccessary. In fact, I think the administrator is
  directly involved more often than necessary throughout the document.

  Also, what does one do about artifact types that don't fit cleanly
  into a single category? Suppose I publish a document that contains a
  schema with annotations that contain the prose specification. Is
  that a spec or a schema or something else? Do I have to get the TC
  adminstrator involved to decide?

Line 275 introduces dates of the form "YYYYMMDD".

  Can we please the ISO standard YYYY-MM-DD format? And does this mean
  that I can't use "23 Feb 2006" as the date on the cover page of my
  specification?

Line 283 makes PDF and HTML the mandatory normative formats.

  This is an error. There must be exactly one normative form of the
  specification. Any other state of affairs will lead to irresolvable
  conflicts in the future. (The TC will produce it's work then disband.
  Three years later, Hugecorp and Megabiz will discover that they're
  software isn't interoperable because the HTML and PDF forms are
  different.)

  It remains my opinion that OASIS should standardize on XHTML as the
  normative form for prose specifications and that it ought to provide
  precisely the markup to be used for the beginning of the document
  that includes all the metadata.

  Extensive experience publishing dozens, perhaps hundreds, of
  documents on the W3C TR page has convinced me that the metadata will
  be wrong if it cannot be checked by machine. Getting all the
  metadata right is simply the kind of boring, detail-oriented work
  that human beings are just not cut out to perform. Even diligent and
  consciencious editors will not get it right.

Line 302 says I have to get the TC adminstrator to approve version
         numbers.

  You're joking, surely? If I produce DocBook v4.5 this month, I have
  to explicitly get permission to produce v4.6 in June?

Line 317 introduces the "TC defined name"

  I don't understand this section. It begins by saying that this is a
  name for "the" artifact, then goes on to give an example that
  contains more than one artifact. It speaks of "effectively defining
  a container" without explaining what that means. I applaude the example,
  but I think it would be valuable to include a more complete example.

Line 332 reads "In the absence of an OASISdefinedName for certain
         artifacts only a TCdefinedName is used"

  What does that mean? Under what circumstances is the OASISdefinedName
  absent? For which "certain" artifacts is only a TCdefinedName used?

Line 346 reads "Selected metadata SHALL be included in the name of the
         artifact pursuant to the related separate documents"

  What does that mean? What related persuant documents?

Line 348 says that if I invent new metadata, I need the TC administrators
         approval

  Who decides if I've invented metadata? If I include some other name
  value pairs in my document, are they metadata? How can you tell?
  This seems unduly burdonsome and impossible to enforce.

Line 350 introduces a table that contains both "Artifact identifier"
         and "OASIS Defined Name".

  When are these different? And why? I thought they'd be the same in
  the normal case. If they're the same, must they both be present?

Line 352 says that the templates will be updated.

  When? Are they ready now? I request that the review of this document
  not be considered complete until such time as the membership has had
  a chance to review those templates.

Lines 374 and 375 indicate "revision|r00|" and "revision|r00|diff|00|"

  Is the "r" a literal part of the revision? If not, I think it's
  confusing in the example. If it is, shouldn't it also be in the
  number after "diff"?

Line 408 defines the characters allowed in Artifact Identifiers.

  Is the absence of "%" intentional? It would seem to preclude the
  ability to encode non-ASCII characters in the name.

Line 408 reads in part "The Artifact Identifier SHALL be exclusively
         in the [ECMA-6] character set..."

Line 415 reads in part "The Artifact Identifier may be expressed in
         other encodings..."

  I find this baffling. I wouldn't even know how to begin to send you
  a name encoded in a 7 bit character set. I think you simply mean
  that it must consist only of the specified characters. But in that
  case, how does it's encoding matter and where does UTF-16 come into
  play? I think you'd be better off just describing the allowed
  characters in terms of Unicode code points and leave the whole issue
  of encodings off the table.

Line 362 introduces "tcShortName" as if it was a placeholder, a variable
         if you will.

Line 433 then uses "tcShortName" as if it were a defined term. But the term
         defined (on line 334, I believe) was "TC Short Name".

  The mapping from defined terms to the short string versions needs to
  be defined for all the terms. This comes up again on 496 where
  "tcShortName" is used as a token in the name attribute on <meta>.

Line 433 suggests that the tcShortName is optional because it can be
         uniquely determined from the product.

  This is news to me. Where, in this specification or elsewhere, is it
  made mandatory for all product names to be unique across all TCs?
  That seems really unnecessary.

Lines 438 and 439 say that the "stage" is optional for schema and wsdl
      artifact types

  Why? Where is the rational for this. What makes them different from
  catalogs or guidelines or any other type of artifact? If I invent a
  new artifact type, do I get to say if the stage is optional? If not,
  who does? The TC administrator, I assume, but it isn't stated.

  I think it's wrong to make the stage optional for some types and not
  others.

Line 443 introduces a similar relaxation of the rules for revision when
     the artificat type is schema.

  Why? Where is the rational for this. What makes schemas different from
  catalogs or guidelines or any other type of artifact? If I invent a
  new artifact type, do I get to say if the revision is optional? If not,
  who does? The TC administrator, I assume, but it isn't stated.

  I think it's wrong to make the revision optional for some types and
  not others.

Line 448 says "A value for TCdefinedName MUST be included if the
     OASISdefinedName is not used"

  What does this mean? Included where? There's no slot for "TCdefinedName"
  on line 429.

Line 451 introduces section 6 "Filenames"

  I have no idea how Filenames differ from Artifact Identifiers
  (section 5). Are artifact identifiers not always filenames? I'm
  completely confused by this distinction.

Line 482 says filenames MUST bear a reasonable and descriptive
     relationship to the document title

  Reasonable and descriptive to whom? And what is the document title
  for a schema or stylesheet? At the very least, I think this should
  be a SHOULD as I don't see how it can be enforced.

Line 509 introduces structured comments.

  Yuck! Can we please not? Can we just say that it should be included
  in some practical way?

Line 646 reads "docs.oasis-open.org/[product]

  Surely "docs.oasis-open.org/[tcShortName]/[product]" was intended?
  Ditto lines 653 and 669.

Line 655 reads in part "open.org/[tcShortName]/index.php"

  Surely "open.org/[tcShortName]/[product]/index.php" was intended?

Line 675 introduces the Latest Version Subtree.

  How does this work, exactly? Suppose exampletc publishes

     product-v1.0-spec-wd-01.html
     product-v1.0-schema-wd-01.rng
     product-v1.0-schema-wd-01.xsd

  Is docs.oasis-open.org/exampletc/product/latest a directory that
  just contains an index file that points to

     docs.oasis-open.rog/exampletc/product/v1.0/product-v1.0-spec-wd-01.html
     docs.oasis-open.rog/exampletc/product/v1.0/product-v1.0-schema-wd-01.rng
     docs.oasis-open.rog/exampletc/product/v1.0/product-v1.0-schema-wd-01.xsd

  or is

     docs.oasis-open.org/exampletc/product/latest/product-v1.0-spec-wd-01.html

  supposed to return the v1.0 specification? If the later, what happens
  when 1.1 comes out? Or do I simply misunderstand.

                                        Be seeing you,
                                          norm

[1] http://www.w3.org/TR/webarch/#avoid-uri-aliases
-- 
Norman.Walsh@Sun.COM / XML Standards Architect / Sun Microsystems, Inc.
NOTICE: This email message is for the sole use of the intended
recipient(s) and may contain confidential and privileged information.
Any unauthorized review, use, disclosure or distribution is prohibited.
If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message.

PGP signature