Not writing docs is practically a programmer tradition. But have you ever wondered why “literate programming” — a concept that’s been around for 40 years — never really took off?

Three months after writing a piece of code, you look at it and have no idea why you wrote it that way. A teammate asks, and you mumble: “Well… it was to handle some edge case…”

Imagine if a document had captured your exact thinking at the time.

Literate Programming: Great Idea, Terrible Maintenance

Over forty years ago, Donald Knuth introduced the concept of “literate programming.” The core idea is simple: code shouldn’t be a pile of cold machine instructions — it should read like a narrative that humans can follow, with code woven in as part of the story.

Sounds great, right?

But anyone who’s tried it knows the fatal problem: you have to maintain two things simultaneously — the code itself, and the prose that explains it.

Picture this: you write a function, revise it three times with completely different approaches each time. Every change means updating both the code and the accompanying explanation. Your workload just doubled.

That’s why literate programming stayed a niche curiosity. The most common real-world example is data scientists using Jupyter Notebooks — they genuinely need analysis steps and results side by side. But for developers writing everyday business logic, the overhead is too heavy.

Something Has Changed

Then AI agents showed up.

Claude, Kimi, and their peers have a masterful grasp of markup languages like Org Mode and Markdown. They don’t complain about “too much syntax,” and they never cut corners when syncing documentation.

This unlocks a completely new workflow:

You tell an AI agent: “Write me a runbook in Org Mode format.”

The AI integrates the code and explanatory docs for you. Your job is just to review, approve, and run.

Here’s how the workflow actually looks in practice:

  1. Ask the agent to write an Org Mode file covering the test steps and corresponding commands
  2. During review, the prose explains the intent of each step; code blocks are executable right there
  3. Results are stored directly in the file, just beneath the code — like a Jupyter Notebook
  4. Want to change the code? Have the AI sync the prose. Want to tweak the explanation? Have the AI update the code. Both tracks stay in sync

What used to require manual upkeep — that dreaded dual-narrative — the AI now maintains tirelessly.

Why Agents Are Uniquely Suited for This

The reason is straightforward: literate programming’s biggest pain points happen to be AI’s greatest strengths.

  • Translation and summarization: turning code into plain language, or plain language into code
  • Keeping things in sync: re-organizing documentation after every change, without ever getting tired of it
  • Org Mode’s complex syntax is a non-issue for a language model

You can even drop an AGENTS.md file into your project instructing the agent: “Treat this Org file as the single source of truth. Always tangle before executing.”

And it will just do it.

There’s an added bonus: the codebase can be exported into multiple formats for comfortable reading. If the primary role of engineers gradually shifts from writing code to reading it, this will matter more and more.

Any Downsides?

Of course.

Org Mode is tightly coupled to Emacs — that’s a real legacy constraint. The original author acknowledges that a Markdown-based equivalent would be more widely adopted, but Markdown lacks the metadata capabilities needed to replace Org properly.

Also, this workflow has so far only been validated for testing and documenting manual processes. How it performs on a large, serious codebase is still an open question.

Should You Try It?

Yes, it’s worth a shot.

Especially if you’re already using an AI agent to help write code — you can just as easily have it maintain documentation at the same time.

Getting started is simple:

  1. Install an Org Mode plugin (available for both Emacs and VS Code)
  2. Next time you ask Claude for help, add: “Keep a record in an Org file”
  3. Run through it once and see what you think

Whether large codebases can truly become “readable as a novel” is a question worth watching.

Programmers no longer have to agonize over whether to write documentation — AI can write it, and you just review and approve. Forty years after literate programming was conceived, this might be its closest brush with going mainstream.

Related Tools

FAQ

What’s the difference between literate programming and just writing comments?

Comments are scattered fragments embedded in code with no narrative structure. Literate programming flips the model: the document is primary, and code is embedded within it. The result reads as a coherent whole.

Do I have to use Org Mode to do literate programming with Claude or other AI agents?

Not necessarily. Org Mode’s advantages are its code block metadata (like specifying which machine to run on) and tangling functionality. But if you just want AI to record your steps and results, Markdown will get you most of the way there.

Is this approach practical for large projects?

No real-world evidence yet. The original author (Ian Whitlock) uses it primarily for testing and manual process documentation. Whether it scales to production codebases remains an open question.