Iteration in Literate Programming

2026-08-10 · 2 min · #computing

Literate Programming is the process of writing documentation embedded with source code, rather than writing them separately as is more usual with software engineering. This provides a collection of benefits, but it requires reshaping how you think about the software development process.

When I'm writing a literate program, I start with the literate document. I write the basic boilerplate accepted by ReTangled. Then I structure the program logically with headings, describing how of each part of the program works in natural language. Finally, I write the code, following the descriptions I wrote in natural language. Sometimes those descriptions are minimal, little more than a typical API doc comment. Other times those descriptions are detailed explanations of the control flow of a process.

But once that is done, I now have two versions of the program: one in natural language and one in a computer language. Iteration from here has become more complicated. I have to modify the program in two places. On the one hand, it forces me to think twice about any new feature I want to implement and everything is now documented by default. On the other, it's a pain for fast iteration.

Most literate programs I've seen, including my own, have embraced fast iteration over full documentation. As far as I can tell, the new version of Entangled (a tool for Literate Programming) has eschewed it altogether.

It's possible this is a sign that literate programming isn't worth pursuing, at least not in the traditional Knuth-style. However, I still have hope for its future, because I believe in the value of documentation.

Most programs should be described in natural language before being written in a computer language. This allows using one mode of thinking while modifying the codebase before switching to another. It also enables considering design decisions at a high level before worrying about the details. This is often done through design documents and such, but those are often abandoned once the code is brought into existence.

So, going forward, my approach is going to be to prioritize iteration in natural language for my literate programs. I will consider what I want to change, write the description of it in natural language, and then implement it in code. That way everything is always fully documented, and I'm forced to fully think through design decisions before they're implemented.