---
name: documentation_habits
description: Writing docs people actually read: READMEs, runbooks, and decision logs. Use when asked to document a project, write a runbook, record an architecture decision, or improve existing docs. Ships with copy-ready templates.
---

# Documentation Habits

## Purpose

Most docs fail because they're written for a writer, not a reader. This
skill teaches three documents that carry 90% of a project's communication
load — a README that answers "should I care?", a runbook that works at
3am, and a decision log (ADR) that stops future teams from re-arguing
settled choices — with templates that keep each one short and honest.

## Workflow

### 1. Decide which document the situation needs

| Need | Write | Rule of thumb |
|------|-------|---------------|
| A stranger finds the project | README | Answer "what is this and should I care?" before asking them to install anything |
| A known failure will recur | Runbook | One failure mode per runbook — not a general troubleshooting guide |
| A technical choice will be questioned later | ADR | If it took more than an hour to decide, write it down |

Default scope is three documents max. A README links outward to guides,
API references, and FAQs — it does not swallow them.

### 2. Draft from the template, don't start blank

- README → `references/readme-template.md`
- Runbook → `references/runbook-template.md`
- ADR → `references/adr-template.md`

Fill every section, then delete the writing-notes block at the bottom of
each template — it's scaffolding for the writer, not content for the reader.

### 3. Apply the reader-first pass

Before calling it done, run these checks in order:

1. **Three attention tiers.** The first screen must carry: project name,
   one concrete value proposition, and the fastest path to a result
   (install command or code example). A 30-second reader sees what it does;
   a 60-second reader gets a first result. Push everything else down.
2. **Concrete over vague.** "p95 latency > 1000ms for 5 minutes" beats
   "API is slow". "Run `cmd`, expect `output`" beats "check the logs".
   Every diagnostic step has an expected output; every action has a
   verification check and a rollback path.
3. **Own every sentence.** Each fact lives in exactly one place — link to
   the canonical source, never duplicate. Name an owner: "someone should"
   means nobody does.
4. **Honest limitations.** State what the thing does NOT do. Runbooks say
   when to escalate instead of keep trying. ADRs record what the chosen
   option costs.
5. **Current state only.** Describe how it works now. History lives in git —
   don't narrate evolution ("we used to use X") in user-facing prose.

### 4. Close the maintenance loop

A doc without a refresh rule rots. Attach one:

- README: review on every release — flag it in the release checklist.
- Runbook: re-verify the commands after any topology or deploy-pipeline
  change; a year-old runbook lies about the system.
- ADR: never rewritten — status moves to `superseded` or `deprecated` and
  the new record links back.

## Output Contract

- Delivered file is valid Markdown, copy-ready, with no writer-scaffolding
  left in (template "writing notes" sections stripped).
- README answers the three attention tiers in order: what, why-care,
  first-result.
- Runbook covers one named failure mode: alert → symptoms → diagnose
  (copy-paste commands with expected output) → mitigate → rollback →
  escalation → postmortem link.
- ADR covers one decision: status, context, decision sentence, options
  considered with rejection reasons, honest consequences. Stored at
  `docs/adr/NNNN-title.md`.
- Every factual claim (commands, endpoints, versions, owners) is verified
  against the real project — never invented to fill a template section.
  Leave a `[TODO: verify]` marker rather than guess.

## Operating Rules

1. **Never invent to fill a template.** An empty section with a
   `[TODO: verify]` marker is better than a confident fabrication.
2. Write for the reader's job, not the writer's convenience: the README
   reader is deciding, the runbook reader is paged, the ADR reader is
   judging a past choice.
3. Keep SKILL.md's scope to these three documents. Tutorials, full API
   references, and contributor guides are linked from the README, not
   authored here.
4. Short beats complete. If a section answers no important reader question,
   cut the section — don't pad it.