The Anti-Documentation Manifesto
Documentation is useful when readers can trust it. A document that describes changing software but does not change with it becomes a liability.
The graveyard
Documentation graveyards are common: old diagrams, onboarding guides for retired tools, renamed APIs, obsolete runbooks, and decision records superseded somewhere else.
These documents may have been accurate when written. The software changed; the documents did not. Readers discover that only after following them.
Documentation is a second description of the system. Two descriptions drift unless tests or tools keep them aligned. Keep documents that explain what code cannot, and give each one an owner and a way to verify it.
Why prose goes stale
Documentation decays because it has no compiler.
Source has feedback. Types reject some inconsistencies, tests catch some behavior changes, and users expose others. The feedback is imperfect, but executable material is exercised in ways most prose is not. Prose can remain wrong silently until somebody relies on it.
A new engineer following stale setup instructions has to decide whether the error is in the environment, the product, or the guide. One bad experience makes the rest harder to trust. An outdated runbook can tell an engineer to perform the wrong procedure under pressure. Google's emergency-response guidance makes the same point: runbooks earn trust by being practiced. A stale description can also make a reasonable decision wrong for the current system.
What we keep
For system behavior, source and tests are authoritative. We keep prose for purpose, non-obvious decisions, user-facing contracts, and operating obligations code alone cannot explain.
We prefer generated references over copied lists, executable examples over pasted output, and tested procedures over unexercised instructions. A concise overview and a repository map help readers find the source of truth.
Readable code reduces how much prose is required. Direct interfaces and short paths expose behavior. Tests demonstrate contracts and fail when expectation and implementation diverge.
Code cannot explain every reason behind a decision. New engineers need orientation. Regulated work requires specific records. Users deserve clear instructions. We preserve the information code cannot carry, keep it close to the work, and give it an owner.
The objection is not to writing. We are writing this document. The objection is to unverifiable duplication. Write readable code, executable examples, tested procedures, and comments that explain non-obvious decisions. Delete prose that no longer earns maintenance.
Documentation should explain what the system cannot say for itself.