Sat 1 Jul 2006

A Side-Effect Of Specifications

I learnt something today. Actually, I think I learnt it again; for about the tenth time.

The hidden advantage of a well-written specification is that you can read it without needing to be aware of all the drama that went into creating it.

In this case, it was the Atom Publishing Protocol specification. Reads well on the outside; looking under the covers was depressing, though.

Last Wednesday evening, I sat down and started to try to convert the latest (at the time) draft of the Atom Publishing Protocol into code (since then, an updated draft has been released). I did some design work and fleshed out how the information flow will work. In general, I was reasonably happy with how it was coming together. I have some experience points in the area of turning specifications into code. It is often fun.

Naturally, I came away with some questions, since I have not followed the Atom Protocol development at all. So this afternoon I sat down with the latest draft in hand and started going through the atom-protocol archives to try and work out my concerns. In the end I found it easiest to grab the 19.5MB archive, drop it into my mailer and read through the threads that looked useful.

The result? Some greater understanding for sure. Some bits where I'm still a bit at sea, but nothing in the showstopper category. I should be able to finish the code now, although there are some places where I still have truly no idea what is "recommended" or "typical" behaviour. This isn't a case of Buridan's Ass, rather that a specification such as APP omits a lot the rationale for things and at this stage that seems to mean going to the mailing list archives and spending a few quality hours.

Which brings me to my real (and disappointing) "take home" lesson from the afternoon: just how antagonistic the whole process was. A lot of lack of respect for other peoples' opinions or intelligence (for example, you could say something once and believe that people will read it. Reposting the same comment every four or five times in a thread is just childish and diguises the content in noise). Disagreements happen in professional situations and when intelligent people get together to design something. But reasonable debate behaviour exists not just as an example of social graces, but because it tends to lead to effective information exchange. It was just a generally unpleasant unexperience.

Reading through the email threads today does not make me want to read more by many of the posters. It also does not make me want to subscribe or even revisit much to try and work out the points of confusion. I can't be too atypical here; how does that help adoption?

My respect for people doing the chairing and secretarial work, such as Tim Bray and Sam Ruby has increased though. And I already had high opinions there. The whole experience would have me bouncing off the walls and yet I haven't read any headlines like "Atom mailing list poster found on spike at the side of the road". Such restraint.

The IETF process seems designed to help a confrontational group arrive at a document that is reasonably clear and useful. The process looks to be working (or, at least, worth it) with APP. Having needed to see the sausages being made, it leaves a bad taste at the moment. Still... I will not be (completely) dissuaded. It would be nice to write something that is more useful than just my client talking to my server software. It may just take longer than I originally thought.

Topics: technology/xml/atom