[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [oasis-member-discuss] Re: Membership and Public Review of OASISArtifact Standard Identification Scheme for Metadata
Norm - Thanks again for your dedication in reviewing. My notes are interleaved. Norman Walsh wrote: >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. > Which sections specifically? (I should be wearing a bullet-proof vest, I think!) >* 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. > It depends on the focus; if TC-defined names are used (as permitted) there might be less of a perceived problem. But I'd also like to know with what version/oasis standard an artifact belongs. >* The draft specifies two normative formats. I remain of the opinion > that this is an unacceptable state of affairs. > The TC Process, Section 2.18, mandates this. I think that XHTML (rather than HTML) should be in the next version of the TC process, and that the PDF is extremely useful for reviews such as this. This is a complex issue, but not one that the TAB is trying to resolve here. >* 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. > Good point. In many cases the TC Administrator involvement is to ensure consistency and reasonableness, rather than trying to describe all possible alternatives up front. >* 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. > Yes, it would. There's a bit of a circular wait - in some earlier versions the examples weren't completely in sync with the then-rapidly changing document; OASIS staff intended to do detailed examples as part of the endgame. >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]. > The intent is to allow a full consistent naming structure (on docs.oasis-open.org) even though some content is there already. The alternative is to remove support for the old, promised-persistent URIs, or to do another domain (documents.oasis-open.org?). I'd say this nmight be the best of a set of bad choices. >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. > Good point. Starting with the (non-normative) grammar might help a bit, but the motivation and goals need to be in the document proper. >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?" > so is "docs.oasis-open.org" OK? :-) Good suggestion. >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? > The intent was to approach the list as a cache, creating new cache elements as the need arose. There needs to be an adminstrative locus, and TCAdmin seems the logical place. On TC Admin decisions, creating persistent names is partially the responsibility of the TC and partially that of TC Admin/OASIS; the synchronization point is when the TC Admin agrees. >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? > Alas, the hyphen issues strike again. And 23 Feb 2006 is fine by me, but the metadata format also needs to be there. Do you have better separator character than hyphen to use in artifact names and URIs? >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. > This is a broader topic, and will be addressed, but not here. The TC Process calls this out. BTW, if the source is the same, the tools work, and people review it, there's seldom a difference between the actual text of the PDF, (X)HTML, and (say) a word processor document that generates both. >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? > The TCA approval is intended to be part of publishing a spec; it makes more sense (I suspect) than saying that "the next minor version is always OK, and the next major version with resetting the minor version to zero is mostly OK..." >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? > This text needs to be reworked. Going backwards from the grammar might help, but not enough. How about we chastise the editor? >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? > Confusing. Good point. >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. > See the caching analogy above. Good point. >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? > Compromise along the way - the earlier drafts mandated a particular format name, in a specific character set (which is now called an OASIS Defined Name); later drafts relaxed this to allow meaningful unambiguous names as defined by the TC as an alternative, reasoning that the TCs should be able to keep track of their own artifact names. Either way works.; >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. > The templates currently in use have reflected these guidelines, and have for some time. >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"? > Needs clarification. >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. > Yes, it was intentional. A future revision will address IRIs. >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. > You're right; listing the code points in any encoding would work, and should be done. >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>. > Good point. >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. > I believe that the OASIS TC Adminstrator said that this was the case; product is the IPR container. >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. > Original motivation, I think, was to allow a single schema namespace URI without requiring a change for each developement version of a spec. This is existing practices in a number of TCs. >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. > You're right; I'd assume the same thing. > I think it's wrong to make the revision optional for some types and > not others. > the development argument seems persuasive to me. Happy to discuss further. >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. > good point again. >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. > Artifact identifers need not have form, in fact the philosophy is that there is an artifact with (potentially) mulitple forms; Chris's point about relaxNG and xsd schemas is a case in point, as is (x)html and pdf. >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. > TCAdmin as part of the publication process for a persistent URI. And no, they won't catch everything. >Line 509 introduces structured comments. > > Yuck! Can we please not? Can we just say that it should be included > in some practical way? > Do you have an alternative? I don't like structured comments either, but the alternatives would seem to affect the actual content, which could break applications. >Line 646 reads "docs.oasis-open.org/[product] > > Surely "docs.oasis-open.org/[tcShortName]/[product]" was intended? > Ditto lines 653 and 669. > Good point; the unique determination of TC from product would make either OK, but some (including you) dispute that.... :-) >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. > Needs clarification. The first is intended. Thanks again for your careful reading! bill > > Be seeing you, > norm > >[1] http://www.w3.org/TR/webarch/#avoid-uri-aliases > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]