Arnt Gulbrandsen
About meAbout this blog
2009-10-14

Arnt rants and rambles on 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 (ie. literate programming in Knuth's sense).

Writing isn't merely a way to produce words; the 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.

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

Finally, I have two more longish posts about the writing process, one about how to write a single documentary description and one about how Trolltech's documentation process evolved and worked, and two about the tools I've written, one about their history and evolution and one that compares my tools to doxygen and javadoc.