Documentation Rot
Documentation that has drifted from the system it describes, and is now worse than none.
Documentation rot is the gradual divergence of written descriptions from the system they describe. It is not a tidiness problem: confidently wrong documentation is more expensive than absent documentation, because a reader trusts it and spends time hunting for a thing that no longer exists.
Rot has a structural cause. Code and its description live in different files, change through different actions, and are validated by different gates — usually none, for the description. The general remedy is to reduce the number of places a fact is stated. A tool's own description, shipped in the same declaration as its implementation, cannot drift; a catalogue of tools maintained in a separate document will. Generating reference material from the source of truth beats maintaining a parallel copy.
Where duplication cannot be removed, it can be checked. A rule requiring every module to be named in a sibling document, or a build step that regenerates types and fails on any difference, converts drift into a red build. See Continuous Integration and Schema Drift.
Rot also afflicts prose inside source files. A docblock is only attached to a declaration by adjacency, so inserting anything above it silently reassigns it to the wrong neighbour — see Code Comment.
See also6
Hand-picked in the note itself — the neighbours worth reading next.
Code Comment
Prose inside source code, useful only when it records a constraint the code cannot state.
Method9 connections
Deprecation
Marking something as superseded and scheduled for removal, without removing it yet.
Method9 connections
Technical Debt
The future cost of a present shortcut, metaphorically accruing interest.
Method11 connections
Provenance
The recorded origin of a change or a claim — who made it, when, and on what evidence.
Method18 connections
Plausible Mechanism
A causal explanation that was inferred rather than tested, and reads as more rigorous for being specific.
Method19 connections
Chesterton's Fence
Do not remove something whose purpose you cannot explain.
Method11 connections
Related2
Nearby in the graph rather than deliberately chosen. Looser, sometimes surprising.
Linked from18
Notes elsewhere in the wiki that reach for this one.
- Agent MemoryAgents & Language Models
Durable facts stored outside the context window and recalled into later sessions.
- Agent SkillAgents & Language Models
A packaged, invocable set of instructions that loads into an agent's context on demand.
- Branching ModelVersion Control & Delivery
The convention governing what branches exist, what they mean, and how work reaches production.
- Chesterton's FenceMethod
Do not remove something whose purpose you cannot explain.
- Code CommentMethod
Prose inside source code, useful only when it records a constraint the code cannot state.
- Code ReviewVersion Control & Delivery
A second person reading a change before it lands, and the practices that make it worth the time.
- DeprecationMethod
Marking something as superseded and scheduled for removal, without removing it yet.
- Feature FlagData & Content
A runtime switch that decouples shipping code from enabling behaviour.
- NamingMethod
Choosing identifiers so the code states its own meaning without commentary.
- PromptAgents & Language Models
The text supplied to a language model to elicit a response.
- ProvenanceMethod
The recorded origin of a change or a claim — who made it, when, and on what evidence.
- Schema DriftData & Content
Divergence between a schema and the code, types, or documentation that describe it.
- System PromptAgents & Language Models
The standing instructions that frame every turn of a conversation with a model.
- Technical DebtMethod
The future cost of a present shortcut, metaphorically accruing interest.
- Tool UseAgents & Language Models
Giving a model a set of callable functions so it can act on the world rather than only describe it.
- Trunk-Based DevelopmentVersion Control & Delivery
Everyone integrating into one shared branch continuously, with short-lived feature branches.
- WikiMeaning & Society
A collection of interlinked pages that anyone with access can edit, named for the Hawaiian word for quick.
- ZettelkastenMeaning & Society
A note-taking method built on small single-idea notes linked to one another.