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:
- How to Compare URIs - which may end up getting sucked into the next revision of RFC 2396.
- "Deep Linking" in the World Wide Web, which will probably remain a standalone document, a message from the TAG to the world.
- Resource Directory Definiition Language, the result of a lot of history and dialogue, and in fact largely written by my co-author Jonathan Borden. Some successor of this may well end up as a W3C Recommendation.
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.
