https://www.thario.net/tags/documentation.htmlRecent content in Documentation on Software Engineer and HobbitHugo -- 0.166.0en-usThu, 17 Sep 2026 20:52:54 -0700https://www.thario.net/post/the-reader-in-the-machine.htmlThu, 17 Sep 2026 09:00:00 -0700https://www.thario.net/post/the-reader-in-the-machine.html<p>In <a href="https://www.thario.net/post/raising-the-floor-again.html">Raising the Floor Again</a> 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.</p> <p>Donald Knuth saw the shape of this in 1984. &ldquo;Let us change our traditional attitude to the construction of programs,&rdquo; he wrote. &ldquo;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.&rdquo; He named the practice literate programming: the program as an essay, with the working code extracted mechanically from the prose (<a href="https://doi.org/10.1093/comjnl/27.2.97">Knuth, 1984</a>). The practice won a devoted minority and lost the field. Writing for human readers carried no enforcement, and the readers skimmed.</p> <p>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.</p>