"Clean Specs"

[Ronald Bourret]

Tim Bray wrote:

> And as regards the namespace spec, I think that some people on this
> list are substantially full of shit, 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 at ic.ac.uk
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 at ic.ac.uk the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)