# Documentation Discipline > Decide what and when to write down, and produce Architecture Decision Records (ADRs), one-pagers, runbooks, and decision logs. Use when the user asks whether something should be documented, wants to write an ADR, needs a runbook or operational playbook, wants to keep a decision log, or is trying to decide between a one-pager and an RFC. NOT for auto-generating docs from code (use documentation-generator). NOT for end-user tutorials or how-tos (use example-design). NOT for docs-site information architecture (use navigation-design). NOT for cross-team alignment via RFCs (use stakeholder-alignment). - Skill: `viktorbezdek/documentation-discipline` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add viktorbezdek/documentation-discipline` - Raw SKILL.md: https://api.skillmd.com/api/skills/viktorbezdek/documentation-discipline/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: viktorbezdek (https://skillmd.com/u/viktorbezdek) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/viktorbezdek/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 ```markdown # 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) | | ADR | Decision doc | |---|---|---| | Scope | Architecture only | Any decision | | Storage | In repo, numbered | Anywhere (docs, wiki) | | Mutability | Immutable once accepted | Can be updated | | Purpose | Long-term architectural record | Accountability + reference | 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 ```markdown # 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. ```markdown # 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: ```markdown # [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 | File | Contents | |---|---| | `references/adr-template-examples.md` | ADR template, worked examples across domains, supersession chains | | `references/runbook-framework.md` | Runbook template with verification, game-day exercises, rot detection | | `references/documentation-decision-tree.md` | Full decision tree (what to write, when, which artifact) with examples | ## 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.