documentation-disciplinelisted

# 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 ```markdown # ADR-NNNN: [Title — a noun phr