Documentation Discipline

Documentation Discipline

Under-documentation forces re-discovery. Over-documentation forces maintenance. The discipline is to write what will be re-used, at the altitude it will be re-used, and to let the rest stay in chat.

What to write down (the decision tree)

Is the question likely to be asked again?
├── No  → don't document (Slack thread is fine)
└── Yes → keep going ↓

Is the answer likely to change often?
├── Yes → runbook or FAQ (owned + dated)
└── No  → keep going ↓

Is the answer a decision with long-term consequences?
├── Yes → ADR (immutable, numbered, dated)
└── No  → keep going ↓

Is the answer operational (how to do X)?
├── Yes → runbook
└── No  → one-pager or reference doc

Red flags that you are under-documenting:

• The same question comes up every quarter.
• New hires ask the same question every cohort.
• "Tribal knowledge" is a phrase anyone uses non-ironically.
• A critical operation has to be learned by watching someone else do it.

Red flags that you are over-documenting:

• Docs are out of date within a month of writing.
• More than 20% of docs have no owner.
• Searches return 5 contradictory answers.
• Writing the doc took longer than doing the thing.

Architecture Decision Records (ADRs)

An ADR captures an architecture decision and the reasoning behind it. Once published, an ADR is immutable — if the decision changes, you write a new ADR that supersedes the old one.

ADR template

# ADR-NNNN: [Title — a noun phrase]

**Date:** YYYY-MM-DD
**Status:** Proposed / Accepted / Superseded by ADR-MMMM / Deprecated
**Deciders:** [names]

## Context
What forced the decision? What constraints exist? What was true when this was decided?
(Keep short — 1-3 paragraphs. Do not re-litigate history.)

## Decision
What did we decide, stated as a present-tense claim. One paragraph.

## Consequences
- **Positive:** what we gain
- **Negative:** what we give up
- **Neutral:** what we accept (trade-offs not clearly positive or negative)

## Alternatives considered
- [Option] — why not chosen (one sentence each)

Rules:

• Numbered sequentially, never renumbered, even when superseded.
• Stored in the repo at a known path (docs/adr/NNNN-title.md or architecture/decisions/).
• Immutable after Accepted. Corrections are new ADRs, not edits.
• Small. An ADR is 1-3 pages, not a design doc.
• Short titles. "Use PostgreSQL for primary storage" — not "Database Selection Framework v2".

Full ADR templates and examples in references/adr-template-examples.md.

ADR vs decision doc (in stakeholder-alignment)

Use ADRs for choices that shape the system (language, framework, primary storage, auth model). Use decision docs from stakeholder-alignment for everything else.

Runbooks

A runbook is a steps-to-follow document for an operational task. It assumes the reader is competent but has never done this specific thing.

Runbook structure

# Runbook: [operation name]

**Owner:** [name / team]
**Last reviewed:** YYYY-MM-DD
**Related:** [links to other runbooks/ADRs]

## When to run this
[Trigger conditions.]

## Prerequisites
- [ ] [access / tool / context]

## Steps
1. [Action] — expected result: [what you should see]
2. [Action] — expected result: [...]
3. [Action — if step 2 failed, go to rollback]

## Verification
- [ ] [Check]
- [ ] [Check]

## Rollback
[How to undo, step by step.]

## Troubleshooting
- If you see [symptom], do [thing].
- If you see [symptom], escalate to [person/channel].

Rules:

• Expected result per step. A runbook without expected results is a wish list.
• Rollback is non-negotiable. If there's no rollback, say "irreversible" and explain what validates before proceeding.
• Last-reviewed date. Older than 6 months → revalidate before relying on it.
• Owner, not orphan. Every runbook has a named owner who owns its accuracy.

See references/runbook-framework.md for patterns including game-day exercises, dry-run verification, and runbook rot detection.

Decision logs

A decision log is a chronological list of decisions at team or org level. Not the same as ADRs (architecture) or decision docs (individual decisions). A decision log is an index.

Format: one row per decision, with date, title, decider, link. Purpose: "what have we decided recently?" answered in 30 seconds.

# Team decision log

| Date | Decision | Decider | Link |
|---|---|---|---|
| 2026-03-15 | Adopt pnpm over npm | @lead | [doc](link) |
| 2026-03-28 | Ship feature flags via GrowthBook | @platform | [ADR-0012](link) |

Used by: new joiners catching up; post-mortems tracing decision chains; retrospectives asking "did we decide this right?"

One-pagers

A one-pager states an idea in one page so people can react without a meeting. Different from a proposal (which asks for approval) or a pre-read (which supports a meeting).

Structure:

# [Idea] — one-pager

**Owner:** [name]
**Status:** idea / exploring / paused

## What
[One sentence. What is this idea?]

## Why
[Problem it solves. Evidence it's real.]

## How (sketch)
[Two-paragraph outline. Not a plan.]

## Open questions
- [ ] [question]

## What I want from you
[React? Poke holes? Push forward? Kill?]

Rules:

• Actually one page. If it's two, it's a proposal.
• "What I want from you" is mandatory. Without it, readers don't know if they should respond.

Anti-patterns

• Write-once docs — written to prove the work happened, never read. Symptom: no ownership, no updates.
• Docs as performance — long, well-formatted docs that repeat what's obvious. Signals effort, carries no new information.
• ADR mutation — editing an accepted ADR instead of writing a new one that supersedes.
• Runbooks without verification — steps without expected results. Untestable, so they decay silently.
• Decision theater — recording decisions that were never in doubt. Log the contested ones, not the obvious ones.
• Doc-firsting — requiring a doc before any action. Appropriate for architecture; paralyzing for bug fixes.
• Over-indexed on ADRs — ADRs for non-architectural decisions (tooling preferences, UX copy). Use the right artifact.

The write-it-down test

Before writing, ask:

1. Will this be read more than once? If no → don't write it.
2. Is there a specific reader in mind? If no → the doc has no audience, don't write it.
3. Is the answer stable enough to justify writing? If no → write a FAQ or don't write.
4. Who owns it after you publish? If no one → don't publish; assign an owner first.
5. When will it be reviewed next? Put it in the calendar.

If you cannot answer all five, you are not ready to write. The alternative is a message in chat — often the right choice.

Workflow

1. Decide whether to write at all. The five-question test.
2. Pick the artifact. ADR, runbook, decision doc, one-pager. Smallest viable.
3. Name the owner. Before publication, not after.
4. Draft using the appropriate template.
5. Peer review before publish. Someone who was not in the decision reads for context gaps.
6. Publish with a review date. 3 / 6 / 12 months depending on volatility.

References

Related skills

• stakeholder-alignment — RFCs and decision docs for cross-team decisions.
• structured-writing — structure each document well.
• clarity-editing — make each document readable.
• documentation-generator — for auto-generated code docs (README, API docs).
• navigation-design — docs-site information architecture.
• example-design — end-user tutorials and runnable samples.