Everyone likes good documentation — unless they have to write it themselves, right?

One reason for this is that writing good documentation is hard, very hard in fact. It took Joseph Heller eight years to complete “Catch-22” and many other novels took even longer to write. As a countermeasure, some authors use a pipelined approach to writing (see Gerald M. Weinberg, “Weinberg on Writing: The Fieldstone Method“) that nevertheless allows them to release in shorter time-frames by working on many projects in parallel.

Speaking as a developer, documentation gets into my way of doing other, more enjoyable things, like, well, coding, for instance. I’m writing (!) this article to the defense of the poor chap who has been given the ungrateful job of writing version 1 of a document.

Imagine this situation. One of your team members, let’s call him Jack, is given the task of finding out how to setup a new development environment for some embedded Linux development board. After a week of trial and error he finally gets everything to work properly. Now — of course — he is expected to document what he did so that everyone else on the team can set up their own boards, too. Being a professional developer he sits down and types away; an hour later, he is finished.

What happens next is typical: Harry, the first guy who tries out Jack’s HOWTO, runs into problems. Not one — many. In some cases essential steps are missing, while others are confusing or just plain wrong.

Harry is upset. He runs about and whines how bad the documentation is, what a poor job Jack did and how unfair life is in general…

For sure, in a perfect world, Jack would have written a perfect document that lays out the shortest route from A to B; it would be instructive, entertaining, a work of great pedagogical value. In real life, Jack is exhausted. He had been a pioneer for an extended period of time, tried out many things that didn’t work, suffered hours of frustration and got stuck in a rut many times. Most likely he operated under time pressure and even more likely he doesn’t exactly remember what he did (and did not). Isn’t it a bit too much to expect that he now takes the perspective of the uninitiated developer and writes the perfect manual?

In my view, Harry shouldn’t complain — he should rather spend his energy on improving the document. He benefits tremendously from Jack’s pioneering work and I think it is only fair if he contributes a share. And what he can contribute is something that the original author can’t: When he reads Jack’s document his mind is fresh and clear, without any assumptions, so he is the best person to tune the document for the same kind of audience. And Jack is always there to support him — provided Harry didn’t insult him for not doing his job properly…

But even the next guy after Harry might spot mistakes or inconsistencies; and many month later people will discover parts that are obsolete because the environment has changed in the meantime. Then, it is their job to clean up; they are again the best persons to do it.

Writing good documentation takes both, a different mindset and time; and as the writer’s saying goes: “All good writing is rewriting”. Especially in an agile environment it is a bit too much to expect to get everything from a single person. XPers have long been used to this mode of software development through the principles of collective ownership and refactoring. I believe, these principles apply to writing documentation as well.