"Clean Specs"

Tue Feb 9 01:13:37 GMT 1999

This may be a little off topic, but here is something I wrote for a magazine
some time ago. I hasten to add that this draws on several years experience
and bears no relation what so ever to any specs I may have edited for the
W3C.

"How specifications get written"
================================
"This is a true story, only the facts have been changed to protect the
inocent"

Axiom 1.
"A camel is a horse designed by a committee"

Axiom 2.
"Those who can do, those who can't write specs, and the remainder criticise
them."

20 people sit in a room. After a lot of discussion, some of it pretty heated
something approaching a consensus emerges. The chair man has already
seperated 'Bob' and 'Matt' who at one time appeared to be on the verge of
coming to 'fisticuffs', and they both agree that they can live with the
current compromise. It should be noted that 'Fred' has been quiet throughout
the whole of the meeting.

This is put into a document by Karl who is fairly experienced at writing
specs. At this stage it is a coherent, logical, well-written document.

The deadline to go public is 10 days hence.

The document is posted for internal review.

d-day minus 10 to d-day minus 5
Not a single suggestion or comment is made.

d-day minus 5 to d-day minus 2
Several people suggest minor alterations mainly of a textual nature. These
Karl incorporates into the draft.

d-day minus 2
Fred posts a long rambling e-mail to the mailing list which can be fairly
described as a mixture of gobbledy-gook and vitriol.  He re-opens all the
old wounds as well as making three suggestions described by him as 'vital'
that have never been mentioned before.

d-day minus 1

Bob, and Matt post rancarous postings saying how they completely agree with
Fred and disagre with each other. They appear to have entirely reversed
their positions from the previous meeting. It is obvious to the Chair that a
tele-conference needs to take place, so this is organized for the next day.

The tele-conference takes place lasting an hour and a half. No body gets any
where, the Chair makes a whole series of executive decisions. Karl is asked
to incorporate every ones suggestions, plus the 'executive decisions' into
the draft. In the last 30 seconds of the tele-conference he tries to clarify
what every ones position is.

He posts a revised draft, uncomfortably aware that it is no longer the
co-herent document that it once was.

Karl is immediately innundated with outraged e-mails from the cheif
protagonists, Bob, Matt, and Fred asking him why he has deliberately
distorted their views. He also gets pointed questions from the rest of the
group asking on what authority he has altered material that had already been
firmly agreed on by the whole group.

This is just before the weekend. Karl having spent most of his free time in
the last month trying to get the spec in order has been threatened by his
wife that unless he takes her away for the W.E, she will strongly consider
divorcing him.

Karl passes the buck to the Chair.The Chair and the Staffer, neither of whom
are technical writers, cobble something together as best they can by
blurring over the more controversial parts of the spec, and adding all the
comments from the most vocal of the protesters.

This is then published as a 'working document'.

----- Original Message -----
From: Marcus Carr <mrc at allette.com.au>
To: <xml-dev at ic.ac.uk>
Sent: Monday, February 08, 1999 6:13 PM
Subject: Re: "Clean Specs"

>
>Lauren Wood wrote:
>
>> On 8 Feb 99, at 9:14, James Robertson wrote:
>>
>> > Well, has anyone considered employing real, professional technical
>> > authors to write the specifications?
>>
>> As chair of the DOM WG, I (and I think the editors of the specs)
>> would be overjoyed were someone to volunteer the services of a
>> real, professional technical author who could help in the process of
>> getting good specs out the door. However, as has been pointed out
>> by others on this list, this support is difficult to find, as W3C
>> seldom has these resources available.
>
>Should we assume from this that TBL's day ends with emptying the rubbish
bins and vacuuming
>the office? James' suggestion is right on the money - this shouldn't be
considered to be a
>luxury, it should be an integral part of the process.
>
>To me, this whole debate taking on the feel of a programmer being thrown to
the mercy of the
>client while the project manager stands by watching. Even if Tim Bray did
have doubts about
>the namespace recommendation (and I have no reason to believe that this is
the case), he (like
>anyone else) feels that he has no option but to defend what we consider to
be at least partly
>"his work". We shouldn't be snarling at Tim and he shouldn't be snarling
back - the whole
>process should be elevated to discussion between the wider community (the
client) and the W3C.
>Obviously Tim's input would be valued (as would that of the programmer),
but any
>dissatisfaction needs to be directed at the organisation. I'm hardly an
expert on the workings
>of the W3C, but it appears that this form of interface doesn't exist.
>
>The developer community aren't the only victims of the W3C process - it
appears that the lack
>of support results in those who write the recommendations also joining this
hallowed group. If
>the W3C wants to retain ownership (or whatever you want to call it) of the
initiatives, then
>they need to provide support for the creators and accept responsibility for
the results. This
>would result in a) discussions related to phrasing and construction of the
recommendation
>being directed to one trained in the creation of spec documents, and b)
technical discussion
>being directed to an organisation, not an individual who might
(theoretically) have difficulty
>abstracting best practice from satisfaction in the finished product.
>
>Where's the project manager?
>
>
>--
>Regards,
>
>Marcus Carr                      email:  mrc at allette.com.au
>___________________________________________________________________
>Allette Systems (Australia)      www:    http://www.allette.com.au
>___________________________________________________________________
>"Everything should be made as simple as possible, but not simpler."
>       - Einstein
>
>
>
>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)
>
>

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)