On documentation and literate programming, etc.

Over the next many months, I'm going to write a long series of semirelated postings on source code documentation, covering the techniques I developed at Trolltech and extended for Archiveopteryx, what other people are doing and what I think of it all.

Update: Done, and below are links to the major postings.

What I write about is largely API documentation, although often for internal readership. Literate programming as conceived by Knuth and described in the book Literate Programming is closer to implementing a program and writing a user manual together. Knuth wrote something brilliant in one long sitting (OK, with pauses to sleep), my topic is writing a large number of small blocks that together describe an evolving software complex, and use tooling to combine human-written text with other input to produce optimal output. Most programmers aren't as clever as Knuth, myself included, and because of that I think literate programming isn't used any more.

That is, literate programming in Knuth's sense. Some people describe the kind of writing supported by javadoc, doxygen etc. as literate programming, because it does mix code and documentation. Knuth might disagree, but he doesn't have a unique right to define the term. I personally don't really care.

Writing isn't merely a way to produce words; the writing process is valuable in itself, and the toolchain can produce more than just text. In my opinion all tools used by software developers can and should produce diagnostics to help produce the software. A compiler shouldn't just produce .o files of today's source code, it should help the developers reach the goal of bug-free software faster. Ditto for documentation tools.

Documentation is related to FAQ lists and support questions and some people think the source is documentation, I'm not of that opinion.

Most documentation processors emit HTML. Other formats do exist, though, each with its own characteristics. Some emit garbage.

Finally, I have three more longish posts about the writing process, about how to write a single documentary description, how to write anything factual and how Trolltech's documentation process evolved and worked, a blog posting about how to write class documentation and two about tools I've written, about their history and evolution and comparing my tools to doxygen and javadoc.