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)