The Documentation Stack: Seven Doc Types, Seven Jobs

One Doc, One Job

There is a specific failure mode that appears when a README becomes an ADR, when a runbook picks up API reference material, when a post-mortem grows into a design document. The failure is audience confusion: each doc type has a primary audience and a specific moment when it is read. A doc that tries to serve two audiences at two different moments dilutes itself into serving neither well.

Before building any documentation type well, you need the map: what exists, what each piece is for, who reads it, and what breaks when it is misused.

Seven types. Seven jobs. The matrix has five columns: type, job, primary audience, failure mode, and lifecycle. That last column is often ignored — and it is where most documentation errors happen.

The Seven Types in Detail

README — orientation. The README answers four questions: what is this, how do I run it, where are the key files, what will bite me. Its primary audience is the impatient senior engineer and the coding agent on first contact. The failure mode is marketing copy — adjective-laden descriptions that answer none of the four questions. The next lesson covers the README in full.

Agent context file — operating instructions. The newest type in the stack. This is what CLAUDE.md, AGENTS.md, and similar files are: persistent session-start instructions that a coding agent loads before touching code. The job is different from a README — a README orients, a context file operates. It carries hard rules, commands, and gotchas. It does not carry stale state, essays, or anything derivable from reading the code. The “Agent Context Files” lesson covers this in full.

PRD / Spec — intent definition. A PRD is where human intent is made precise enough for an agent to act on without judgment calls. This track assumes the spec-driven-development prerequisite track — if you have not done it, go there first. In one sentence: a PRD without testable acceptance criteria is a wish list. This track does not re-teach PRDs; it treats them as a given input to the rest of the documentation stack.

ADR — decision history. An Architecture Decision Record captures Context → Decision → Consequences. Its value is not the decision itself — it is the constraints that made the decision necessary. Six months later, when a new engineer (or agent) looks at an odd architectural choice and considers "improving" it, the ADR is what prevents relitigating a settled decision. The critical rule: accepted ADRs are immutable. You never edit one; you supersede it with a new one. The “ADRs” lesson covers this.

Runbook — operations under pressure. A runbook is written for 3am-you, an on-call stranger, or an agent given a deployment task with no additional context. The structure: preconditions, numbered steps, exact copy-paste commands, expected output after each step, rollback. The failure mode is liveness verification where artifact verification is required — "verify the service is running" when the correct check is "verify the new version is serving on the correct host." the “Runbooks” lesson.

Lessons / Post-mortem — the learning loop. Every correction is an opportunity. A lessons entry takes the form: Mistake → Root cause → Rule. The rule goes into the context file, which every future session reads. This is the compounding mechanism — without it, agent quality resets to zero each session instead of improving. Post-mortems are the bigger-picture version: timeline, root cause, detection latency, alerting gap, the rule. The “The Learning Loop” lesson.

Contract / API reference — interface truth. An API reference is not just documentation — it is the interface contract that callers depend on. The failure mode is drift: the hand-written reference diverges from the implementation, and callers (human or agent) build against a lie. The solution is generation: the reference is derived from the schema, not hand-authored alongside it. When the source changes, the reference changes automatically. The “Docs as Contracts” lesson.

The Lifecycle Problem

The matrix's lifecycle column distinguishes three states: living, immutable, and generated. Most documentation errors are lifecycle errors.

The lifecycle map shows how each doc type moves through its stages. Notice that ADRs have an "accepted" state after which they become immutable — not deprecated, not archived, not updated. Immutable. The runbook has a "verified" state that represents the first time it was actually executed end-to-end — until that state is reached, the runbook is an untested claim, not a runbook.

The lessons file's "promoted" state is particularly important. When a lessons entry keeps appearing across multiple sessions — the same mistake keeps recurring — it has graduated from a lesson to a rule that belongs in the context file itself. The lessons file is the queue; the context file is where durable rules live.

Immutable vs. Living vs. Generated

Three lifecycle categories, three very different relationships with time.

Living docs (README, context file, runbook) are meant to change. A README that was accurate at project launch and is never updated will fail the orientation test within a few weeks. The discipline here is systematic update — not "when I remember to," but "whenever the corresponding code changes." Good CI hygiene enforces this: a PR that changes the service architecture should require a README update.

Immutable docs (ADRs, post-mortems) must not change after they are finalized. Their value is historical fidelity. An ADR that gets cleaned up, polished, or "updated to reflect current understanding" has had its value destroyed. The original reasoning — the constraints that made the decision necessary at the time — is exactly what you want preserved, even after those constraints no longer apply.

Generated docs (contract / API reference) should not be hand-maintained at all. If the source schema is the truth, and the contract doc is derived from it, they cannot drift — by construction. The human-maintained equivalent of a generated doc is a liability: it requires a discipline tax on every code change to stay in sync. That tax is rarely paid consistently.

The Doctrine Behind the Taxonomy

The taxonomy is not administrative overhead. It is the answer to a specific question: "why are we writing this, for whom, and when will they read it?" Without that answer, docs accumulate into a pile that confuses every reader — including the agents that now constitute the primary audience for half of them.

At jeremyknox.ai, the documentation stack for Mission Control and the trading infrastructure follows this taxonomy exactly. The README is orientation only. The context files carry operating instructions. The ADRs record why certain architectural constraints exist. The lessons files carry the rules that prevent repeated mistakes. When an agent is dispatched against any of those codebases, the taxonomy means it spends zero time inferring what a doc is for — the structure makes the purpose immediately readable.

In the next lesson, we build the first and most-read piece: the README.