Verso

Tim Bray's remarks on the death of documentation are typical of many engineers I've encountered over the years. For example, the chief architect at an application server company I used to work for thought that documentation was a symptom of incomplete or unintuitive tools. That is, the existence of documentation was an engineering flaw, and that a sufficiently well designed piece of software would not require any explanation.

Tim Bray's thinking is not quite so extreme, but the assumption is similar: coordinated documentation efforts are hopelessly flawed endeavors. Why not cut out the middleman and just have the users and engineers write the documentation, in the form of a Wiki where problems could be posted and solutions contributed for all to see?

I should point out that Udell's article was about solving the problem of technical support docs, but Bray picked up a few overtones in the article about documentation in general being crappy and sort of ran with it.

Personally, I fail to see the necessity of an excluded middle here.

First of all, the set of products or pieces of software that could be documented completely through a user-written Wiki isn't very large, because the product/tool needs to be fairly simple for a tabula rasa user to even know where to start with it.

Secondly, although I find Google and mailing list questions and forum postings quite useful for solving specific problems, these little snippets of information do not make a coherent whole. A related point is that the people posting the questions are often familiar with the system generally, in fact are expected to be familiar with the system, and are having problems with a particular area. What is the standard response to newbies who post general questions like: How does $PRODUCT work? RTFM.

Thirdly, the probable success of shunting the responsibility of writing doc onto the users, with contributions from engineers, is highly unlikely, to put it mildly. Somebody has to do the thankless job of writing this crap, engineers rarely have time to even review the material produced by doc teams (to say nothing of actually doing it themselves), and there is something to be said for coherent, grammatical, and style-checked prose when using ever-more-complex technology.

So, I'll conclude with a proposal that is hopefully obvious when you think about it: Wouldn't it make more sense to deliver the documentation in a format that could accomodate general discussion of the system as well as user supplied questions and answers? Merge the manual with the Wiki, yo? Some projects do this, like the PHP docs online and the PostgreSQL docs.