> Documentation standard for agent-maintained projects — from The Handover, the-handover.org/docs/documentation-standard
> Authors: Leon Mallett (captivated.online) with Claude Code · Last confirmed working: 2026-08-25
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

How to document a software project so the next person — or the next agent —
can reconstruct not just what the code does, but why it is like that.

This describes a **set of linked documents**, not a single file. It applies to
any project; nothing here assumes a particular language, framework or size.

## The shape: a linked set, not a pile and not one long file

Documentation lives in `{{docs_path}}`, one file per section, with an index that
links to all of them. Documents link to each other using {{link_style}}.

The structure matters for two reasons that pull the same way:

**A single long document cannot be partially loaded.** An agent needing the
testing approach should not have to read the commercial plan to find it, and a
context window spent on irrelevant sections is context not spent on the work.

**An unlinked pile gets orphaned.** A file nobody links to is a file nobody
finds, and it rots without anyone noticing because nothing points at it to go
stale. Links are what make the set navigable and what make staleness visible:
a link to a feature that no longer exists is an obvious defect, while a
paragraph about a feature that no longer exists is invisible.

## File naming

Fixed, so that links are predictable and an agent arriving in an unfamiliar
project can guess the path before looking.

```
{{docs_path}}README.md            index — links to everything below
{{docs_path}}about.md
{{docs_path}}architecture.md
{{docs_path}}licensing.md
{{docs_path}}features.md
{{docs_path}}decisions.md
{{docs_path}}test-strategy.md
{{docs_path}}security.md
{{docs_path}}runbook.md             for anything deployed or shipped
{{docs_path}}roadmap.md
{{docs_path}}commercialisation.md   optional

{{docs_path}}user-guide.md          user documentation, if the project has users
  OR
{{docs_path}}user/                  the same, as chapters, with a README.md index
```

Some files belong at the **repository root**, not in the set, because tooling and
convention expect them there: `README.md`, `LICENSE`, `SECURITY.md`,
`CHANGELOG.md`, and whatever instruction file your agent reads. Code hosts treat
several of these specially, and moving them costs behaviour you want.

The root `README.md` and `{{docs_path}}about.md` overlap enough that both get
written and one rots. Give them different jobs: the root README orients someone
who has just arrived at the repository — what this is, how to run it, where the
documentation is — and `about.md` explains what the software does for the person
using it, at length and without jargon. If the README grows past a screen, the
surplus belongs in the set.

The rules behind those names:

- **Lowercase, hyphen-separated, `.md`.** Case sensitivity differs between
  operating systems and hosts, so a link that works on one machine can fail on
  another; lowercase removes the question entirely.
- **No spaces.** They require escaping in relative links and are a persistent
  source of broken references.
- **No numeric prefixes on sections.** They encode an order that changes, and the
  index already provides order.
- **`README.md` is the single uppercase exception**, because code hosts render it
  automatically when someone browses the directory. That behaviour is worth more
  than the consistency it costs.

**Consistency matters more than the specific scheme.** Most tools are flexible;
what breaks is a project where two conventions coexist and links guess wrongly
between them. Pick these names, or pick others and apply them everywhere.

**When a section outgrows one file**, promote it to a directory with the same
name and a `README.md` index inside: `{{docs_path}}features/`,
`{{docs_path}}decisions/`. Features and the Decision Log are the two that
normally get there first. Decision entries are the one place a numeric prefix
earns its keep — `decisions/0007-use-server-side-rendering.md` — because there
the number is a stable identifier to link to, not a sort order.

## The set records when it was last confirmed

The three writing rules below all depend on currency — update in the same change,
date anything version-dependent, delete what has stopped being true — and none of
them can be checked without a reference point. Nobody can tell a current
`architecture.md` from one that stopped being true in March.

So **`{{docs_path}}README.md` names the commit the set was last confirmed
against**, and any file that rots faster than the rest carries its own line:

```
Last confirmed against: a1b2c3d (2026-08-25)
```

That single line is what converts an instruction into something that holds. It
makes staleness **detectable without anyone judging the prose**: read the commit,
diff it against the current head, and report that the architecture was confirmed
at a point since which forty files have changed. No opinion about quality, no
word count — just a fact that goes out of date visibly.

It also guards the set against its own most likely failure. Documentation does
not usually fail by being absent. It fails by being present and wrong, which is
worse, and which nothing else here can detect.

## The sections

Each is its own file. Omit one only when it genuinely does not apply — an empty
section is more honest than a missing one, because it tells the reader the
question was asked.

### About

A plain-English explanation of what this is and who it is for. No jargon, no
architecture, no justification. Someone unfamiliar should finish it able to say
what the software does.

This is the one section a non-technical reader will read. Write it accordingly,
and resist letting it drift into a feature list.

### Architecture

The components, what each is built in, which external libraries carry
significant weight, and how the parts interact. High-level: this is the map, not
the territory. Individual components are documented in Features.

**Include a diagram**, and write it as text — Mermaid or similar — rather than
embedding an image. A text diagram diffs, survives being edited by an agent, and
does not silently disagree with the prose after a refactor. An exported image
does all three badly.

Link each component to its entry in Features.

### IP Rights and Licensing

A log of every third-party component and the licence it carries, plus any
obligations the project takes on as a result — attribution requirements,
share-alike terms, restrictions on commercial use.

This is the section people skip and later need urgently, usually the week
someone asks whether the project can be sold, open-sourced or shipped to a
client. Reconstructing it retrospectively means auditing a dependency tree
under time pressure; maintaining it costs a line per dependency.

Record the project's own licence and any deliberate constraints here too.

### Security

The threat model, and a record of what has been examined and what was found —
each entry naming the commit it was assessed against.

**Call it a self-assessment unless it was genuinely independent.** "Audit" claims
an independence that reviewing your own project does not have, and the claim is
weaker still when the reviewer is the same kind of thing that wrote the code: it
carries the model that produced the fault into the review of it. A self-assessment
that names its commit is honest and checkable. One that does not is neither.

Record what was *not* examined as carefully as what was. A gap nobody wrote down
reads as coverage.

### Runbook

For anything deployed or shipped. Operating a live service and responding when it
breaks is a discipline of its own — what this section must contain is set out in
the operational rootnote, and this is the file it lives in. Link it from
Architecture.

Omit it only for software that nobody runs but you.

### Features

A detailed technical explanation of each component. This is the bulk of the set
and the part most at risk of becoming code narration.

For each feature: what it does, the shape of how it works, and **links to the
files that implement it** rather than transcriptions of them. Code examples
where an example genuinely clarifies — a non-obvious call sequence, an unusual
contract — not as illustration of what the reader could read directly.

Each feature links to its decisions and to its tests. Those links are the
skeleton of the whole set.

### Decision Log

One entry per non-obvious decision: what was decided, what was rejected, and
what would have to change for it to be revisited.

**Link each decision to the feature or features it governs.** A decision with no
link is usually either architectural — in which case link it from Architecture —
or not really a decision.

Write these at the moment the decision is made. The alternatives are only clear
while you are rejecting them; a week later, only the winner is memorable.

Never delete an entry that turned out wrong. A superseded decision with a note
saying what replaced it and why is more valuable than the replacement alone —
it is the only thing preventing the same idea being tried again.

### Test Strategy and Plans

The overall approach — what is tested, at what level, and what is deliberately
not — followed by specific approaches linked to features.

State the deliberate gaps explicitly. "No integration tests for the export
path, because it requires third-party credentials" is useful. Silence reads as
an oversight and invites someone to assume coverage exists.

### Roadmap

Planned work that does not exist yet, in enough detail to be actionable.

**A roadmap item becomes a Features entry when it is built**, and the roadmap
entry goes away. That promotion is the mechanism that stops the roadmap becoming
a graveyard of things nobody is doing, and it makes "what actually exists" a
question with an answer.

Keeping this current is what stops an agent from confidently implementing
something twice, or building around a feature that was only ever aspirational.

### Commercialisation and Distribution

Only for projects with a commercial dimension. The plan, and progress against
it — pricing, channels, licensing model, whatever applies — updated as things
move rather than written once.

If a project has no commercial dimension, omit the file rather than filling it
with placeholders.

## What to read first

A set exists partly so that an agent can load part of it. Say which part.

For a change to one feature: **`about.md`, then that feature's entry, then the
decisions it links to.** Skip the rest — a context window spent on the commercial
plan is context not spent on the change.

For a change touching how components fit together, start at `architecture.md`
instead. For anything operational, `runbook.md` on its own is usually enough.

The index should say this, so nobody has to work it out from the file list.

## The links are the structure

Four relationships carry the set. Get these right and it stays navigable:

- **Architecture → Features.** Each component named in the map links to its
  detailed entry.
- **Features ↔ Decision Log.** Every non-obvious feature links to the decisions
  that shaped it, and each decision links back.
- **Features ↔ Test Strategy.** Every feature links to how it is verified, and
  every testing approach names what it covers.
- **Roadmap → Features.** On completion, the item moves.

A document that links to nothing and is linked from nothing is the warning sign.

## Writing rules

**Do not narrate the code.** An agent asked to "document this" will by default
describe what the code does — the least valuable documentation and the fastest to
rot, adding nothing while it is correct because the code was already there.
Document what the code cannot say: why this approach, what was rejected, what
breaks if it changes, what looks incidental but is load-bearing, which
constraints are external and not yours to simplify away.

**A useful test:** if a rename would invalidate the sentence, it is describing
mechanics, and mechanics belong in the code.

**Update documentation in the same change as the code it describes.** A
follow-up commit is a commit that does not happen.

**Date anything version-dependent**, and say what it was true of. An undated
technical claim cannot be assessed later.

**Delete what has stopped being true.** A deleted document is honest; a stale one
misleads, and misleads an agent more efficiently than a human, because the agent
has no instinct that something reads oddly.

**No screenshots of code or terminal output.** They cannot be searched, copied,
diffed or read aloud, and they go stale invisibly.

**Spelling: {{spelling_variant}}**, matching whatever the product's user-facing
copy uses. Documentation that spells things differently from the interface it
describes makes both look unmaintained, and it breaks search for anyone looking
up a term they read on screen.

## What is deliberately not here

**A changelog.** This set documents what exists and what is planned; a changelog
records what shipped. That is a release artefact, tied to versions and tags, and
it lives at the repository root. The Decision Log already answers the question a
changelog usually gets reached for — *why is it like this* — and answers it
better.

The absence is a decision rather than an oversight, which is why it is written
down.

## User documentation

Everything above documents the project, for whoever maintains it. Documentation
*for people using the software* is a different thing with a different organising
principle, and merging them serves neither.

It lives alongside the rest, in one of two shapes:

- **`{{docs_path}}user-guide.md`** — a single document, when the whole guide can
  reasonably be read or scanned in one pass.
- **`{{docs_path}}user/`** — a directory of chapters with a `README.md` index,
  when there are distinct task areas a reader would navigate *between* rather
  than read through.

**Choose per project rather than by rule.** The question is whether a reader
arrives wanting the whole thing or one part of it. A utility with a single job
gets a single document; an application where someone might need "importing data"
today and "managing permissions" next month gets chapters, because searching a
long page is a worse experience than picking a chapter. When in doubt start with
the single file and split it when a reader would have to scroll past two
irrelevant sections to reach theirs.

Whichever shape, the writing rules are the same:

- **Organise by task, not by feature.** People arrive wanting to do something,
  not wanting to learn a menu. "Export a report" beats "The Reports panel".
- **Make each step verifiable** by saying what the reader should see, so they can
  tell where it went wrong rather than discovering it three steps later.
- **Use screenshots sparingly and record the version** they came from. They stale
  faster than any other content and nobody notices.
- **Write the uninstall, export and recovery paths.** They are what people search
  for under pressure, and they are almost always missing.

Link the user documentation from the index, and from any Features entry where the
technical and user-facing descriptions of the same thing should stay in step.

## Related rootnotes

This set has two companions, and the boundary between them is worth stating so an
agent reading one does not invent what the others say.

- **The working agreement** governs how changes are made — what may be run
  unattended, what stops for a human, and what an honest report of the work looks
  like. This document governs what gets written down; that one governs how the
  writing gets committed.
- **The operational rootnote** sets out what `runbook.md` must contain and how to
  behave when something is actually broken. This document names the file; that one
  fills it.

## For the agent working here

- **Put every document in a section this standard names.** A well-written file
  in a location nobody expects is not a contribution.
- **Add the links.** A new feature entry that links to nothing has done half the
  job.
- **Do not write documentation instead of doing the work.** A thorough document
  about an unfinished feature is worse than a note saying it is unfinished.
- **Do not silently rewrite an existing document.** Show what changed,
  particularly when removing something — the removed line may be the only
  surviving record of a constraint.
- **When unsure whether something merits documenting, write the decision entry.**
  It is short, it is the highest-value form, and it is the one nobody regrets.