Writing

Last summer I wrote about teaching my assistant to reach and to remember. Reach meant tools for looking at the live world; remember meant a small local database that survives between our conversations; and in both cases my part was to name what was missing while the assistant built the way to fill each gap. I closed that essay on a promise I meant: there would be another gap to name next week. This one was in how the assistant writes. The request was four sentences, sent on a Sunday afternoon. I asked the assistant to research what makes written material pleasant to read. Then it was to analyze the gap between that research and the writing skills it already had, and make a plan to fill it. That assignment carried an irony: I was asking a system that cannot feel anything about a sentence to find out what makes sentences pleasant. The answer stepped around the irony rather than through it. Much of pleasant reading turns out to be measurable. ...

In Raising the Floor Again I wrote that the documentation is no longer a courtesy to the next human. It is load-bearing input to the thing that does the work. If the words are load-bearing, then they are the material, and engineers do not leave material to chance. We engineer it. Donald Knuth saw the shape of this in 1984. “Let us change our traditional attitude to the construction of programs,” he wrote. “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.” He named the practice literate programming: the program as an essay, with the working code extracted mechanically from the prose (Knuth, 1984). The practice won a devoted minority and lost the field. Writing for human readers carried no enforcement, and the readers skimmed. The reader we write for now does not skim. It reads every word, resolves every ambiguity by guessing, and acts on what it reads with tools and credentials attached. The essay Knuth wanted the field to write has found an audience. It is simply not the audience he had in mind. ...