Why Documentation Matters: How a Decision Outlives Its Author

The original question

Why does a program need documentation if working code already shows what the system does?

In April 1943, Robert Serber delivered a series of five lectures at Los Alamos for scientists being brought together at the new research center. Their content became known as The Los Alamos Primer. The document introduced arriving specialists to their shared task: it recorded the initial understanding of nuclear explosion physics, identified the objectives of the work, and gave the group a common language.

The Manhattan Project is useful here as an extreme example of coordination. A large system does not emerge from a single brilliant mind. It requires a way to transfer context between people, laboratories, and successive stages of work. An idea that cannot be communicated remains the author’s private experience. Once the author leaves, it becomes archaeology.

This example immediately reveals the limit of a romantic attitude toward documentation. A well-composed document helped create atomic weapons. Documentation reinforces a chosen intent and makes it teachable and reproducible, but it does not give that intent a conscience. Humanity is generally eager to make a procedure reproducible before it can get ethics as far as a committee meeting.

The question of documentation therefore begins with purpose. A document preserves a decision, but people must still determine the value of that decision.

Code preserves action; a document preserves the decision

Working code tells us what the system does now. It is much worse at telling us why the system does precisely that, which alternatives were rejected, where the boundaries of acceptable behavior lie, and under what conditions the decision should be reconsidered.

The simplest fragment looks self-contained:

if (failedAttempts >= 5) {
	lockAccount(user.id);
}

The code shows the rule. It does not explain the choice of five attempts, the threat model, the duration of the lockout, the acceptable cost of a false positive, exceptions for support staff, or the grounds on which the threshold may be changed. This information may once have existed in a conversation, a task, an email, or a developer’s head. The system will continue to execute the decision after all four sources have disappeared.

Tests record expected behavior. Git history records the sequence of changes. Names and comments explain local fragments. Together they form part of the documentation, but each layer answers its own question. A commit chronology does not yet constitute an argument, and a passing test does not reveal where a requirement came from.

Useful documentation retains four kinds of context:

• intent — what problem the system solves and for whom;
• decision — which option was chosen and why;
• boundary — which conditions, risks, and exceptions constrain the decision;
• verification — what observable behavior confirms that the decision is still being enacted.

Documentation becomes memory infrastructure when the next contributor can reconstruct the reasoning without the author being present. It turns individual knowledge into a shared system resource.

Without this connection, experience quickly becomes hearsay. The decision continues to operate while its rationale disappears, and the team begins to defend an accidental form as a law of nature. This is how programming acquires sacred typos in APIs, temporary workarounds aged for a decade, and database tables treated like archaeological burial sites: touching them is terrifying, their purpose is lost, and the cron sacrifices are still being performed.

A good document preserves the past in a form that can be changed. It identifies the source of truth, revision, decision owner, verification method, and condition for reconsideration. A document that cannot be challenged or updated gradually becomes a ceremonial text. People continue to revere it after the system has ceased to conform to it.

Between intent and voltage

A program connects two scales. At the upper level, a person works with tasks, names, rules, and models of the world. At the lower level, the processor receives instructions and changes the state of registers and memory, while electronic circuits control signals in devices. Compilers, interpreters, runtimes, operating systems, and hardware interfaces operate between these levels.

The formula “liturgy controls voltage” sounds deliberately solemn, but it describes a real engineering structure. The symbolic order of a text causes physical changes because a chain of formal transformations has been built between them. Documentation explains why this particular order exists, which transitions are considered permissible, and which physically observable result is accepted as correct.

It thereby connects human intent to machine behavior. Code participates in this connection as the executable form of a decision. A document retains meaning that machine execution alone cannot prove.

Knuth changes the program’s audience

In 1984, Donald Knuth formulated this problem more radically than the usual call for more comments. In Literate Programming, he proposed treating the human being who needs an explanation of what the author wants the computer to do as the program’s primary audience.

This is the origin of literate programming. Its source material is organized in the order of human understanding: the task comes first, followed by concepts, decisions, constraints, and named fragments of code. Machine order is formed later as a derived representation. The program becomes an explanation from which an executable artifact can be produced.

Knuth implemented this principle in the WEB system. A single source file combined documentary prose with program fragments. The WEAVE utility produced a human-oriented account, while TANGLE assembled code for the compiler:

                  → WEAVE  → document for a human
single WEB source
                  → TANGLE → program for a machine

This arrangement solves one of documentation’s most unpleasant problems: two versions of the truth drifting apart. When two files are independent, code changes faster than its explanation, while the explanation continues to describe a system that no longer exists. WEB connects both projections through a shared source and build mechanism.

Literate programming is therefore a development process rather than decorative treatment applied to finished code. Explanation participates in design. The author must name parts of the program, justify transitions, and discover contradictions before they take the form of an exceptionally confident production failure.

The method’s purpose and limits

The purpose of documentation is to transfer intent, make a decision verifiable, and enable a system to survive changes in its contributors. This purpose establishes its own priorities: clarity over local speed, shared context over personal memory, and reproducibility over the hope that “the author remembers everything.”

Documentation is not a neutral panacea. It selects which knowledge counts as significant, who may change the system, and which actions receive formal justification. A precise document can preserve a misguided decision just as successfully as a sound one. Documentation gains engineering value through the possibility of verification, challenge, and reconsideration.

Knuth himself stated this limit directly. He warned that his experience with WEB was colored by his personal tastes, deliberately did not design the language for everyone, and expected the method to appeal particularly to programmers who enjoy writing and explaining their work. This qualification is part of the model itself. Literate programming requires time, multiple languages, a separate build process, and single-source discipline.

A complete literate process is particularly justified for complex algorithms, research computing, long-lived systems, generators, domain rules, hazardous operations, and projects in which transferring context is expensive. A disposable utility and an obvious CRUD module usually call for a lighter form. The practical boundary lies in the relationship between two costs: the cost of explanation now and the cost of incomprehension later.

A minimal decision document can remain short:

Intent: the problem we are solving.
Constraints: what the environment and risks have already determined.
Decision: what exactly we are adopting.
Alternatives: what was rejected and why.
Verification: what confirms the result.
Reconsideration: what event reopens the decision.

Such a document does not try to repeat the entire codebase. It preserves what cannot be reliably reconstructed from code.

What remained after WEB

Classic WEB retained a niche position, while its central question dispersed across different practices. CWEB and noweb continue the historically close line of generating code from a literate source. Org Babel uses related mechanisms of named blocks and tangling. Quarto, Jupyter, and R Markdown develop executable documents in which prose, code, computation, and results inhabit a single publication workflow.

Modern reproducibility adds the environment. Containers, dependency lockfiles, CI pipelines, and documented build commands preserve the conditions under which source material can once again become a verifiable result. Knuth’s concern remains active here: the source must survive a different machine, a different operator, and a different time.

These practices form several related lines. Direct continuation, instrumental similarity, and conceptual association must be evaluated separately. A notebook does not become WEB merely because text and code are adjacent. An automatically generated API reference does not become a literate program. Each tool should be evaluated by the connection between explanation, implementation, and reproducible artifact.

When AI appears between people

AI-assisted development brings the documentation problem back in a harsher form. In the past, code could lose the intent of a single author. A machine system can now produce thousands of lines whose intent no participant ever fully articulated.

A prompt is useful as an input instruction, and a conversation log as a working record. Both materials require editorial transformation into a project source. A free-form exchange does a poor job of recording architecture, invariants, rejected decisions, acceptance criteria, and the relationship between an accepted result and its tests.

Knuth’s TANGLE deterministically transformed a structured source. A large language model probabilistically creates a candidate from context. Its output therefore receives the status of a proposed artifact and undergoes verification:

human explanatory plan
  → fragment contracts
  → constrained prompt
  → AI-generated candidate
  → review
  → tests and smoke check
  → provenance and decision log
  → accepted update to the canonical source

This loop develops Knuth’s idea under new conditions. The model accelerates the production of a candidate. Documentation preserves authorship of intent, the boundaries of the operation, and the grounds for accepting the result. A prompt alone does not yet become a literate source, just as a conversation about a house does not become one of its load-bearing walls.

Conclusion

Documentation is a way to transmit a decision through time. It preserves intent, explains a choice, marks its boundary, and connects implementation to a means of verification. It allows a system to survive the author’s absence without turning every change into a session of applied necromancy.

The strength of documentation also constitutes its limit. It makes intent reproducible, so the quality and moral direction of that intent remain part of engineering responsibility. A good document enables the next contributor to understand, verify, challenge, and change a decision.

Code preserves the system’s action. A document preserves the decision after the author’s voice disappears.

Publication details

Authors: Sam Starling, Oksana Dubinetska
Project context: Zhovten Games / IRONCREED
Full research paper: Literate Programming: Donald Knuth, WEB, and Modern Workflows
Donald Knuth’s original article: Literate Programming, The Computer Journal, 27(2), 1984
Related method: Prompt-Literate Workflow
Archival material used in the introduction: Robert Serber, The Los Alamos Primer, OSTI
Nature of the research basis: independent methodological review; preprint; not peer reviewed
Publication revision: 1.0 · 2 August 2026