OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

oasis-member-discuss message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Comments on AIR WD 15


Here are my comments on AIR WD 15. I have made comments along these
lines privately and in other forums, but it seems responsible of me to
send these comments to the requested comments list as well. I've taken
the opportunity to clean them up a bit, add some additional rationale,
and append a few detailed notes about draft 15.

[BTW, how do I subscribe to the oasis-member-discuss list? I didn't
see it on the mailing list subscription management form and my mail to
oasis-member-discuss-request seems to have vanished into the ether.]

I feel I must begin with a painful, high-level observation: I think
this document approaches the metadata problem it seeks to solve in
fundamentally the wrong way. I say that with trepidation and a
horrible sense of responsibility since it clearly draws some of its
inspiration from the work that Karl Best and I did in 2001. In the
intervening years, I have changed my position[1] on the central
question of "names and addresses" such that I no longer support URNs
at all for the sorts of artifacts Karl and I were attempting to name.

The URN registration process requires that a new URN scheme describe
its purpose and the procedure used to construct a URN in that scheme
in exact detail. That is why RFC 3121 describes an ontology of
artifacts and a procedure for constructing compound names (URNs) from
the artifacts, their titles, types, versions, and other metadata.

I think adapting that methodology for naming artifacts with http: URIs
is a recipe for frustration and confusion. The process is rigid,
brittle, confusing, and unnecessary. The public will not understand
it, TCs will find it endlessly burdensome, and it will not scale.
Please don't do it.

At the end of the day, a member of the public, looking at a document
produced by an OASIS TC, needs to be able to quickly, easily, and
unambiguously answer some simple questions such as:

  1. What is this?
  2. Who produced it?
  3. Is it the most recent version?
  4. If it's not the most recent, where is the most recent?
  5. What is its status?
  6. When was it produced?
  7. What has the TC done since it produced this?

I propose that you adopt a much simpler alternative to enable readers
to answer these questions. It is not without points over which there
may be controversy, but it has proven to be robust and scalable.

First, decide what metadata you will require every TC to associate
with every document that it publishes officially. (As a corollary, you
want to make sure that every draft that is distributed unofficially is
distinct from all the official drafts.)

AIR draft 15 lays out most of this metadata (and some other elements
that I don't think are necessary under this alternative proposal):

  1. A TC Name
  2. A Title
  3. A Version, if appropriate
  4. A Revision, if appropriate
  5. A Stage
  6. An Abstract
  7. A Language

I think it would make sense to include a few more things:

  8. An Editor (or Editors) Name (or Names)
  9. A Date
 10. A Copyright
 11. Some sort of IPR statement
 12. Links to any appropriate feedback URIs or email addresses

It may be valuable to associate some boilerplate with the document
as well.

Second, require that every TC provide all of this data in a machine
readable form. I propose that the most straightforward way to do this
is to require that the normative version of each specification be
expressed in XHTML and to require that the "title page" of that XHTML
document contain this metadata in a form that is both visible to the
reader and can be extracted by a tool. Readers familiar with the
current trend towards HTML "microformats" will find this technique
familiar.

This may be a point of controversy since the current process allows
the normative version of artifacts to be published in other formats.
Briefly, I think that's a mistake too. The web is how documents are
distributed in the modern world and (X)HTML is the lingua franca of
the web. (The fact that the current process allows the normative
version of a specification to be published in *both* (X)HTML and PDF
is totally unacceptable as it will eventually result in two putatively
normative specifications that do not agree with each other.)

Producing HTML should not be a significant burden for anyone competent
to edit technical specifications. A great many tools will produce it
at the push of a button. It's true that formatting the metadata may
require a little effort, but that's going to be true regardless. The
hardest thing about metadata is getting it into documents in the first
place.

Note that I *am not* suggesting that alternate formats, such as PDF,
should not be allowed. In fact, I think it would be a good idea to
encourage them, as many specifications run to tens if not hundreds of
pages and lots of people are more comfortable reading documents of
that length on paper, nicely formatted. But such alternate formats
should not be described as normative.

As to the URI used for these specifications, I think it would be
sufficent to use the short, administrator approved, product name to
construct the URI as follows:

  http://docs.oasis-open.org/name-of-tc/name-of-product/

The administrator can make sure that no product name is ever reused by
a single TC. I think it would make sense if the URI above identified
the "current version" of the product specification. It would also make
sense to publish a dated URI as well to point to specific versions:

  http://docs.oasis-open.org/name-of-tc/status-name-of-product-YYYY-MM-DD/

As to the naming of various other artifacts associated with the
product (schemas, images, stylesheets, etc.), I think it's probably
sufficient to say that every one of them must be reachable (at least
indirectly) through links from the normative specification.

An obvious question is what to do about existing (and new) Technical
Committees that want to use URNs to identify their artifacts. For my
part, I think they should be allowed to do so. They can still use
guidelines such as the ones I think the AIR document should suggest.
In choosing URNs, they will have volunteered to construct identifiers
of a more constrained sort. I just don't think OASIS should implicitly
or explicitly encourage TCs to adopt them.

A few detailed comments about draft 15:

Section 2, lines 212-214

  I suggest that it is better to leave existing identifiers as the
  unique identifiers for the relevant artifacts. Creating aliases
  can't do anything but cause confusion.

Section 3.2

  I don't see any guidelines for the publication of beta or other
  public test releases.

Section 3.2, lines 269 and 271

  Don't abbreviate. There's no significant savings in using "req"
  instead of "requirements" or "spec" instead of "specification"
  and the abbreviated forms can only cause confusion for non-native
  English speakers.

Section 3.2, lines 315 and 316

  I'll reiterate what I said above: having more than one normative
  format is unacceptable. That said, I think requiring TCs to produce
  specific, proprietary non-normative formats is a mistake. I
  suggested that the requirement be that the TC produce the document
  in a normative format with a note that they are encouraged to
  produce such other, non-normative alternatives as they think would
  be beneficial.

Section 5.2, lines 373 and 374

  This requirement is actively hostile to TCs that conduct business
  in languages that don't use the ECMA-6 character set. That seems to
  be in direct conflict with the TC Process document that allows TCs
  to nominate the language in which they will conduct business.

  If a TC does it's business in Ethiopic, it should be allowed to
  publish Ethiopic document identifiers. How these are mapped to
  filenames on the OASIS servers is not the TCs problem. (In fact,
  RFC 3987 answers this question)

Section 5.5.1

  Who creates the URIs for default product web pages?

Section 5.5.1, lines 434-437 and 441-443

  These sets of nearly adjacent lines appear redundant. Suggest the
  editor reword things a bit here.

Section 5.5.3

  Structured comments are evil. Just say no.

Sections 5.5.3-5.5.6

  I think there's too much detail here. Given the variety of possible
  ancillary artifacts, I doubt that there's much value in trying to
  pin down a few possibilities.

Section 6.3

  Is this really valuable? Most of the test releases that I've
  produced have used the final identifier or something very similar to
  it for namespace names and such. That's what helps users test the
  releases. Having this foreign URN-based approach seems bound to
  confuse users.

Globally

  Change URL to URI.

I appreciate that a lot of work has gone into producing the draft AIR
requirements. I hope that these comments are helpful and I mean no
disrespect to any of the participants in that effort.

                                        Be seeing you,
                                          norm

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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]