What is Living documentation?
Documentation kept current by the process that changes the system, rather than by people remembering to update it.
Docs that depend on goodwill go stale; docs tied to the work stay true.
On this page
Living documentation is documentation whose correctness is maintained by the same process that changes the system — updating the document is part of completing the change, not a favour someone remembers to do afterwards. The term comes from behaviour-driven development practice, where specifications double as executable tests, but the underlying idea generalises: a document is living when the workflow makes staleness expensive and currency automatic.
The ordinary kind — documentation that depends on goodwill — has a well-known life cycle. It is written earnestly, decays silently, and ends up worse than no documentation, because it arrives with the authority of the system behind it while describing a system that no longer exists.
Why the goodwill model fails with agents
Agent-driven work sharpens both blades of the problem.
The consumption blade: agents use stored documentation as ground truth. A human reader skims a stale README with earned suspicion; an agent acts on what the knowledge base says, with the confidence of a system that is supposed to be maintained. Stale documentation is not merely unhelpful for agents — it is actively misdirective, at full speed.
The production blade: agents generate new knowledge constantly — edge cases discovered, failed approaches, corrected assumptions. If capturing that knowledge is optional, it is skipped; the next run pays to rediscover it. If capturing is mandatory and uncurated, the knowledge base drowns in transcripts. Living documentation is the discipline between the two: capture as part of the work, consolidate as part of the work.
What makes documentation living
| Ordinary documentation | Living documentation |
|---|---|
| Updated when someone notices it is wrong | Updated as part of the change that made it wrong |
| No record of what was believed before | Versioned: the correction is part of the record |
| Grows by accretion | Curated: merged, corrected, and retired deliberately |
| Truth decays silently | Premises get checked against the current system |
| Nobody is accountable for staleness | The work that invalidates a claim owes the edit |
The last row is the mechanism. In a living setup, "the change is done" includes "the documents the change affects now describe the world as the change leaves it". That is testable in review, which is what distinguishes a real definition of done from a hope.
Two design habits carry most of the value:
Attach knowledge to its subject. An article about how the migration runner treats empty arrays should be linked to the migration runner. When the code changes, the affected articles are discoverable — and the update happens in the same change, by the same author, while the facts are in context.
Make retirement a first-class operation. The rarest and most valuable documentation operation is deletion. Claims nobody can ground in the current system should be retired deliberately, with a record — not left to whisper indefinitely.
Living documentation vs the adjacent ideas
| Rule files (AGENTS.md) | Raw transcripts | Living documentation | |
|---|---|---|---|
| Who updates it | A human, by hand | Nobody — it accumulates | The workflow itself |
| Stays current | Only with discipline | Never — it is a log | By construction |
| Trustworthy when read | Sometimes | Rarely — noise with the signal | Increasingly, with corrections |
| Cost when read | Small but constant | Large — context rot | Summaries cheap, full text on demand |
The comparison with AI agent memory is close: living documentation is what the curated layer of agent memory looks like when it is done properly — versioned, corrected, attached to the code it describes. Knowledge consolidation is the verb: the ongoing work of folding findings into it.
Best practices
1. Put the update inside the definition of done
A change that invalidates a documented premise is not done until the document says so. Enforce it in review, where "did you update the affected articles?" is a cheap question with expensive consequences.
2. Version corrections, do not overwrite history
When a stored claim turns out wrong, the correction should land as a new version with the old one preserved. Anyone who acted on the wrong claim can discover it; anyone auditing a decision can see what was believed at the time.
3. Keep articles single-topic and capped
A living document that grows without bound becomes a transcript with a title. Size caps force consolidation — merge the duplicates, delete the steps that no longer matter, keep the decision and the reason.
4. Premises expire; check them
A claim about the code is a hypothesis with a timestamp. Before acting on stored knowledge, the actionable premise should be verifiable against the current system — and unverifiable premises are retirement candidates.
Living documentation in YATFA
YATFA's knowledge base is built to be living: versioned articles that agents update as part of completing changes, with corrections recorded and full history preserved; premises attached to the code they describe; size caps that keep articles reference-shaped. See living knowledge — and memory for AI coding agents for the design reasoning, including a real case of an article that corrected its own false claim.
Frequently asked questions
Is living documentation the same as generated documentation?
No. Generated documentation (API references from source comments) is accurate but shallow — it describes the surface mechanically. Living documentation records decisions and their reasons: why the migration runner behaves that way, which edge cases bit the last change. Generation can be a part of it; the living property comes from the workflow, not the generator.
Who updates living documentation when the writers are agents?
The agents themselves, as part of their work — that is the point of tying updates to changes. When a change invalidates a stored premise, updating the article is part of completing the change, and the correction ships in the same review as the code. Humans keep the high-impact gate, under the project's autonomy settings.
What is the first documentation to make living?
The one agents consume most and verify least: conventions, invariants, and the gotchas that cost someone a day. If a run's first hour is spent rediscovering a documented answer, that article is the highest-value place to attach updates to changes.