Literate programming, structured writing and the "long now"
James Strachan: I spotted this Literate programming site today; its a good read. Donald Knuth was a bit of a dude really. Back in 1984 he said...
I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming."
Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.
[Sam Ruby]
The rise of high-level programming languages arose out of such a concern for human understandability. Still, even with those tools, I wouldn't call most code literate. It is too tempting for programmers to settle for the minimum, i.e. make the computer understand and move on to something else. Turning code into literate code requires quite an investment. The payback is a little too far down the road for many people to care.
The idea that is dual to that of literate programming is that of structured writing. Structured writing makes knowledge so much more easily retrievable; it paves the way to the semantic web, as Jon Udell points out i.e. here. There, the problem is the reverse: it is too tempting for writers to settle for the minimum, i.e. make the reader understand and move on to something else.
In both cases I think a key factor in getting motivated to "do the right thing" is to reflect carefully on who our readers really are. In the beginning, we spoke to one person at a time. It was legitimate to try to be understood by that person only, as the words were not recorded. Now that discourse is easy to broadcast and can float around for a very long time, it is increasingly likely that we're writing for posterity. In writing or programming we ought to think of the people might want to use what we're producing. To think long now, in other words.
Now the Web, and tools such as weblogs in particular, is making the feedback loops shorter, so that increasingly we are perceiving first-hand that the value of what we are expressing can reach beyond a restricted circle of acquaintances. In effect, we are collaborating with people that we don't know (yet). The long now is contracting and we are becoming conscious of a "wider here". I think in time this will drive many people to try and do their best in terms of making their output usable by a wider audience. As the feedback comes ever more quickly, it will become increasingly easy to discover, learn and teach each other how to properly do that.
 2:04:10 PM
|
