MHonArc v2.5.0b2 -->
oasis-member-discuss message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: Membership and Public Review of OASIS Artifact Standard Identification Scheme for Metadata
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]