[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] RE: "Clean Specs"
Tim Bray wrote: > And as regards the namespace spec, I think that some people on this > list are substantially full of [expletive deleted], and are wilfully refusing to see > how simple it is because it does not meet their own design prejudices. > I think that spec is *way* better than the XML spec. I've quoted this out of order because I think it is a very important point and one that has bothered me during this whole discussion. Tim is absolutely correct here -- the namespaces spec is *way* better than the XML spec. There is absolutely no comparison, both from an organization and a writing (sentence-level) point of view. I think there are three other things to remember with respect to the namespaces spec. First, no matter how you cut them, namespaces turned out to be far more difficult than any of us could have imagined. We didn't, as is the case in most programming languages, simply get them for free based on where we declared our variables -- we had to decorate variables ourselves. Thus, I think the discussion has often confused frustration about technology with frustration about spec writing. Second, watching a spec evolve is not always the best way to judge how good it is. Throughout this discussion, I have wondered how I would have felt about the namespaces spec had I seen it for the first time in its completed form. No doubt I would have had some confusion, but I also would not have been carrying pre-conceived notions from one version to the next, which is where a lot of my confusion about the relation between attributes and namespaces came from. Finally, we have to remember that namespaces appear to work -- I have yet to hear any examples on this list where they don't. Until such examples arise, I think we have more to gain by agreeing to use namespaces than by going off in our own directions. > This group is notably and vocally dissatisfied with the specs, I > am watching with attention for concrete suggestions as to how > to make future specs better - the one premise that seems to get > consensus, in this group at least, is "more examples". (Hmm, the > namespace spec has tons). OK. Enough being nice. Here's the brickbats :) 1) One idea, one term. The namespaces spec uses three terms (XML namespace, traditional namespace, and namespace) for two ideas -- XML and traditional namespaces. This can lead to confusion, as mail between Mark Birbeck and me shows -- he interprets standalone "namespace" (for example, see the definition of "declared") to mean traditional namespace while I interpret it to mean XML namespace. (Interestingly, the spec can be read using either definition, but it does lead to different conclusions.) A more egregious example is the use of "entity" to mean "general entity" in the XML spec -- this might work for the initiated, but is very confusing for first-time readers. 2) Include negative truths as well as positive truths. In the namespaces spec, an example would be to state that unprefixed attributes are not in any (XML) namespace. Although this can be determined from the fact that there are no statements saying that they *are* in a namespace, it is much easier for the spec to say this than for the reader to work it out themself. The reason this is important is that the definition of an XML namespaces sets the readers expectations by stating that they include attribute names. As another example of negative truths, non-goals are often as useful as goals in setting the reader's expectations. 3) Be explicit about goals. Although the namespaces spec describes its goals in general form in the motivation section, I think spelling these out might have helped a lot. In particular, it would have saved us from having to write "Unique names. Really. Just unique names. Nothing more. Really." in email over and over and over. 4) Organization counts. Organization it is often harder than the writing itself and many writing problems stem from organizational problems. The namespaces spec is very good in this respect. The XML spec is a nightmare. Some easy examples: a) The definition of a document is tucked away in a section on well-formedness. b) DTDs are introduced in the same section as prologs and version numbers, but otherwise spread across the spec, including such things as putting Conditional Sections in section 3 (Logical Structures). c) Section 2.8 tells us that attribute-list declarations in the internal subset take precedence over those in the external subset. This information either belongs in, should be repeated, or should be referenced from the section on attribute list declarations, but is not. 5) Headings matter. They set the reader's expectation for what is to come, and if the section doesn't answer the questions raised in the reader's mind by the heading, the result is confusion even if the section is well-written. Except for Appendix A, the namespace spec does a good job here. My favorite mis-leading heading in the XML spec is "Documents" (section 2), which would have better been titled "Miscellany". 6) Include cross references. Again, the namespaces spec is very good and the XML spec is a nightmare -- trying to find an EBNF definition and the corresponding text when it is not in front of your face is almost impossible without hypertext. 7) As appropriate, include motivation. Admittedly, this is thinner ice, but it can be useful. For example, the motivation for namespace defaults is presumably to reduce the number of prefixed elements. Including this information gives the user something they can immediately grab on to. Similarly, the motivation for allowing namespace declarations on any element is presumably the ability to assemble a document from fragments, as well as the ability to redeclare defaults. Stating this motivation deflects the reader from wondering why on earth anybody would want to keep changing their prefixes. 8) Restate when necessary. This is more thin ice. Succinct statements are useful, but often overly loaded with meaning and difficult to interpret. Maybe I'm just dense, but when I read the statement, "...default namespaces do not apply to directly to attributes", my first reaction was "Huh?" This statement includes two important concepts, neither of which was immediately obvious to me. The first is that: a) The lack of a prefix on an element means it is in the default namespace, if there is one. b) Attributes can also lack a prefix. c) Because attributes can lack a prefix, we are explicitly stating that they behave differently from elements and do not automatically belong in a namespace. The second is that: a) Elements can be in an XML namespace. b) According to the XML spec, elements implicitly have a traditional namespace for their attribute names. c) Thus, defaults apply to attributes indirectly in that they give the (XML) namespace of the element containing the attribute (traditional) namespace. Thus, although the statement is concise and correct, a clarifying sentence or three that restated the same thing would have been very helpful. 9) Emphasize the important stuff; cover the obscure stuff. A spec has an obligation to be thorough, so it must cover everything, no matter how infrequently something is used. However, how it is organized and how much is devoted to each topic strongly influences the reader's perspective. As an example of misleading organization, the XML spec discusses such things as comments, PIs, white space, and CDATA sections before it ever tells us what an element looks like. This gives the impression that these are more important. To the average reader, XML is about elements and attributes and declaring them; white space can be forward-referenced and the rest can be relegated to a later part of the spec without harm. Similarly, the namespace spec could tell us how to use prefixes before telling us how to declare them. This motivates the reader to see the usefulness of namespaces and makes them think, "Cool! Now how do I declare these prefix thingies?" Quantity devoted to a subject can also be misleading. For example, the last example in section 5.2 is the largest in the namespace spec. As a reader, this leads me to believe it is very important, when in fact it covers a seldom-used case. Section 2.12 (Language Identification) is similarly misleading, although the authors in that case might have had good reason to believe it would be more widely used than it has. > Having said all that, people who write specs always have to try to > do a better job next time, so this recent discourse is very very useful. Thanks for listening. I hope this has been helpful. -- Ron Bourret xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev@i... Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1 To (un)subscribe, mailto:majordomo@i... the following message; (un)subscribe xml-dev To subscribe to the digests, mailto:majordomo@i... the following message; subscribe xml-dev-digest List coordinator, Henry Rzepa (mailto:rzepa@i...)
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|