Documentation as Context
Overview
Section titled “Overview”Documentation now has a second reader, and it does not skim. An agent working in your codebase retrieves fragments of your documentation and acts on them, and it has none of the recovery strategies a human has — it cannot tell that a page is three years old from the tone, cannot ask a colleague, cannot notice that a diagram contradicts the text.
This is where the two threads of the guide meet. The claim worth holding is stronger than “also structure it for machines”:
The discipline that makes documentation retrievable is the same discipline that makes it good for humans. It is not a second job.
Why the ADR format is already right
Section titled “Why the ADR format is already right”The useful observation, and it is almost an accident.
Module 4 established what retrieval needs: self-contained chunks, each about one thing, carrying enough context to be interpretable alone, with metadata for filtering. A fragment retrieved out of its document has to stand on its own, because nothing around it comes with it.
An ADR is exactly that. One decision per file. Self-contained — the context section states the circumstances rather than assuming them. Single-topic, so it does not dilute. Dated and statused, which is filterable metadata. And it answers the question an agent most often cannot answer from code: why is it like this?
So the highest-leverage retrieval corpus in a codebase is a well-kept decision set, and you get it for free by keeping decision records properly. That is a genuinely convenient result, and it generalises: the properties that make a document retrievable are the properties that make it readable.
Four properties, both readers
Section titled “Four properties, both readers”graph TD A["<b>One topic per<br/>document</b>"] --> E["Serves <b>both</b><br/>readers"] B["<b>Self-contained</b><br/>no assumed context"] --> E C["<b>Stable headings</b><br/>and stable locations"] --> E D["<b>Dated, with<br/>status</b>"] --> E classDef prop fill:#5B8FB9,stroke:#4A7A9E,stroke-width:2px,color:#ffffff classDef both fill:#7D9A4E,stroke:#5F7A38,stroke-width:2px,color:#ffffff class A,B,C,D prop class E both
Four properties. None was invented for retrieval — each is standard advice for writing documents people can use.
One topic per document. A human scanning for the device-provisioning decision finds it; a retrieval system returns a fragment that is about that and nothing else. A page covering nine decisions serves neither — the human reads past eight, and the retrieved fragment mixes them.
Self-contained. The outsider test from Section 1 is the same requirement. A document whose meaning depends on knowing what is three pages above it fails for a new engineer and fails harder when a fragment arrives alone.
Stable headings and stable locations. Humans build mental maps and bookmark things; retrieval benefits from consistent structure and stable anchors. Reorganising documentation is more expensive than it looks for both readers.
Dated, with status. A human can sometimes guess a document’s age. An agent cannot, and will present stale content with the same confidence as current content. An explicit date and status is the cheapest available defence, and the supersede discipline from Section 1 produces it as a side effect.
Where this diverges from writing for humans
Section titled “Where this diverges from writing for humans”Two places where the interests genuinely differ, and being honest about them matters more than the convenient alignment.
Redundancy. Good human writing says things once and cross-references. Retrieval prefers a little repetition, because a fragment arriving alone needs its own context. The resolution: repeat the constraint that makes a document interpretable, not the whole argument. A decision record that restates the one relevant constraint in its context section costs a human reader a sentence and saves an agent from a wrong answer.
Tone. Humans benefit from emphasis, narrative and the occasional aside. Retrieval does not care, and a document heavy with rhetorical structure retrieves worse. This is a mild tax, not a conflict.
Agents reaching the context
Section titled “Agents reaching the context”Documents in the repository are already reachable by anything that can read the repository, which is the main reason Section 2’s first topic matters here.
Beyond that, the Model Context Protocol is the standard interface for exposing a context source — documentation, a decision index, a diagram model — to an agent as a tool rather than as a pile of files. Module 5’s tool-design discipline applies without modification: a retrieval tool needs a description that says when to use it, not merely what it returns, or the agent reaches for it at the wrong moments.
One warning that follows from Module 6: documentation reachable by an agent is an input to a probabilistic system, and the quality of the corpus sets the ceiling on everything downstream. A stale decision record is now a source of confidently wrong architectural advice, delivered in your own words.
Feeds the workbook
Section titled “Feeds the workbook”This completes the documentation structure artifact, and one rubric item lands squarely here: the structure must let an agent retrieve a specific decision’s rationale. Test it rather than asserting it — name a decision and trace how a fragment about it would be found and interpreted alone.
→ The corpus and the artifacts exist. Somebody has to decide what is enforced. — Governance sized to the organisation