documentation_habits v1.0.0

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.