You have two hours to document a system before handing it over. What do you write, and what do you deliberately leave out?

What is being tested

Editorial judgement. Anyone can list artefacts; the skill is knowing which survive contact with reality.

What to write

1. A context diagram (15 minutes). The system, its users, every external thing it talks to, and one line each on what happens when that thing is unavailable. Almost never wrong, and the first thing any newcomer needs.

2. Decisions and their reasoning (45 minutes). Six to ten short records: what was decided, what the alternatives were, why they were rejected, and what the decision costs. The rejected alternatives are the valuable half — without them the next person re-opens every settled question and re-makes an avoided mistake.

3. The invariants (20 minutes). What must remain true and is not obvious from the code: "job IDs must be globally unique because the downstream deduplicates on them"; "this table must never be updated in place because the audit export reads it as an append-only log"; "the third retry is deliberate — the provider's timeout is 30 seconds."

These exist nowhere else and are what the next person will break in their second week.

4. Operational reality (20 minutes). What pages, what it means, what you actually do about it, and which alert is known-noisy and why it has not been fixed.

5. Known problems (20 minutes). The shortcut, the thing that breaks at 3x traffic, the deprecated dependency, the skipped test. Written honestly this is the most generous thing you can leave behind, and the most commonly omitted because it is unflattering.

What to leave out

• Anything the code says more accurately: class diagrams, endpoint lists, configuration keys.
• Anything stale in a month: instance counts, current traffic, the state of a migration.
• A complete component inventory. Wrong within a quarter and it teaches nothing.
• Setup instructions, unless genuinely undocumented — the README carries those.

The framing that makes it easy

Write for the person woken at 3am in four months, not for an audit. They need to know what the system talks to, what breaks, what must stay true, and why it is like this. They do not need a catalogue.

The general test

For anything you consider writing: who reads this, when, and what decision does it support? If the answer is vague, do not write it — documentation without an identified reader is maintained by nobody and becomes misleading, which is worse than missing.