…as I’ve been reading it I’m struck once again by the theme of narrating the work. Of the chapters I’ve read so far, three are especially vivid examples of that: Karl Fogel’s exegesis of the stream-oriented interface used in Subversion to convey changes across the network, Alberto Savoia’s meditation on the process of software testing, and Lincoln Stein’s sketches (”code stories”) that he writes for himself as he develops a new bioinformatics module.
Although this is a book by programmers and for programmers, the method of narrating the work process is, in principle, much more widely applicable. In practice, it’s something that’s especially easy and natural for programmers to do.
I hadn’t run across the phrase “narrating the work” before, but it’s an apt description of what developers really want in high-level documentation: a story that will lead them into the heart of the code, so that they can understand its view of the world. It also explains why such documentation is so rare: telling stories well is a difficult art.