In connection with my W3C TAG work, in recent weeks I've published drafts or updates of three separate pieces of standards-ware. Writing these things is challenging in a way that nothing else is.

The three recent publications are:

When you're writing one of these things, you're trying to satisfy a bunch of different constraints, many of which are in complete opposition to each other. You want to be complete and precise. Some of your readers will be computer programmers preparing to write code, who need all the facts, in detail, and correct.

You want to be friendly and understandable. There's no reason why a specification should make the reader want to go to sleep or run screaming from the room. Specs that are enjoyable to read will be read more, and implemented more.

You want to be brief. Reading specifications is overhead, and the less time you spend doing it the better. Furthermore, the longer a specification, the greater the number of bugs, ambiguities, and other mistakes it will contain.

The first spec I ever wrote was XML 1.0 (actually, co-wrote with Michael Sperberg-McQueen), which will quite possibly remain the most influential and important thing I will ever write. This is a pity, because in retrospect I don't think it's very good. It's presented in the wrong order, and there aren't enough examples, and there's too much hand-waving.

These days, I've come to think that an ideal technical specification should be composed of:

  • A totally factual, brief-as-possible statement of the rules.
  • One or more illustrative examples for each piece of the rules.

That's right, nothing (or as close to it) by way of explanatory text, tutorial material, background, history, or any of that stuff. If this is an important spec, there will soon be many shelf-feet of books at your local big-box explaining all this stuff in hundreds of pages of well-crafted prose.

The programmers, on the other hand, will look at the examples, and in most cases go write the code on that basis, with occasional reference to the rule statement; they will appreciate the brevity.


author · Dad · software · colophon · rights
picture of the day
February 19, 2003
· Technology (87 fragments)
· · Web (394 fragments)
· · · TAG (11 more)

By .

The opinions expressed here
are my own, and no other party
necessarily agrees with them.

A full disclosure of my
professional interests is
on the author page.