# Writing Docs

> Write or trim habit-hooks documentation under docs/. Use when creating, editing, reviewing or cutting any doc in this repo — keeps docs user-facing, short, and example-first. Exemplar of a finished cut commit f79594fd.

- Skill: `habit-hooks/writing-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add habit-hooks/writing-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/habit-hooks/writing-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: habit-hooks (https://skillmd.com/u/habit-hooks)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/habit-hooks/writing-docs

---


# Writing habit-hooks docs

Everything in `docs/` is user-facing: it onboards a user (install → run → interpret output → configure) or a contributor extending the system. Short, extremely clear, executable examples as the main communication device.

The finished-cut exemplar: `git show f79594fd` — `docs/smell-vocabulary.md` went from 211 lines to 13. What survived: the catalogue table, severity semantics, how to propose a smell. What went: per-plugin translation tables, design rationale, edge-case essays.

## Properties of a doc

**Audience and purpose**
- One doc, one reader, one job — user onboarding or contributor extension. A doc serving both does neither well.
- Answers "what do I do", never "how did we decide". Rationale lives in PRs, commit messages and tests; mechanism walk-throughs live with the doc that owns them (architecture.md for the pipeline).
- Contribution sections state acceptance criteria ("name the smell by the problem it creates, not the tool"), not the reasoning behind them.

**Examples are the message**
- The executable example carries the meaning; prose between examples only supplies concepts and context the example can't show. A paragraph that re-explains what the example demonstrates gets deleted.
- Examples run as written — the spec harness enforces it, which is why examples are the safest device: they can't rot, prose can.
- `*.spec.md` files are documentation first, tests as a side effect. Trimming prose around cases is a docs change; deleting or editing cases changes test coverage and goes through normal test review, not a docs cut.

**Stays true**
- Contains nothing code can answer. State inventories — which tool maps to which smell, which plugins ship which sensors — go stale the release after they're written; link to where the truth lives instead of copying it.
- Each fact stated once. Cross-reference instead of restating; duplicated explanations drift apart.

**Length**
- Every sentence carries a fact the reader acts on. First cut: history, edge-case essays, "deliberate exception" narratives.
- Lead with the organising fact as a definition, in the fewest words. Never advertise what the doc lets you do — that restates the sections and reads as a sales pitch.
- One sitting per doc. A doc that needs a table of contents wants to be two docs — or its headlines to carry their promises, not an index table to carry them.

**Format**
- No hard newlines inside a paragraph; let the editor soft-wrap.

**Boundaries**
- Core docs are plugin-agnostic, same rule as the core code (see AGENTS.md). Per-plugin detail lives in the plugin.
- Concepts defined before first use. "Sensor", "mapper", "smell" mean the same thing in every doc.

## The process — writing or fixing any doc

Run these in order, before writing prose or cutting it. A doc that skips a step is why a reader bounces off it (`docs/config.md` before its 2026-09 rework: no audience, no promise, mechanism-named sections).

1. **Decide who the audience is.** One doc, one reader, one job. Signal it by talking to that reader — never announce who the doc is for, and never narrate what the reader just did ("you open this page to…").
2. **Phrase the reader's expectation on opening it** — one sentence: "I will find out how to disable a rule I don't agree with." If it takes two sentences, the doc has two jobs: split it.
3. **Make the headlines deliver on those expectations.** Name the problem being solved, never the mechanism — not the design name (`## Advanced configuration`) and not the syntax (`[smells.<name>]`): `## Silence or demote a smell`. If a headline can't carry its promise, rename the headline — don't paper over it with a task index.
4. **Make the first paragraph summarise the content and place the doc in context.** The summary itself tells the right reader they are in the right place.
5. **Write each section to deliver on the promise of its headline** — and only that promise. Deliver with executable examples; reference data is a bullet list, `- **key**: description`, never a table and never prose.

## Cutting an existing doc

Fix structure first with the process (audience → expectation → headlines → first paragraph → sections), then cut prose.

1. Delete every sentence whose absence changes nothing the reader does or understands.
2. Delete state inventories code already answers; link to the truth instead.
3. Move per-plugin detail to the plugin, and mechanism walk-throughs to the doc that owns them.
4. If two distinct readers or jobs remain, split into two docs.
5. Keep: reference tables the reader looks up, acceptance criteria, executable examples.

Check: read only the examples — does the doc still teach its job? Then read the prose; anything the examples already said is gone.

Cross-reference other docs with a link, never a summary.

## Before handing over

For every line, ask as the reader with a task in hand, not the writer who wrote it: does the user need this — and is this the one place it is said? Repeated anywhere else, or nothing the user does depends on it → delete.

Intuitive rules (precedence, who-wins) are stated once, at the end, for the reader checking their intuition — never inline at each point of possible conflict.

Examples that demonstrate a default show nothing; the default is already stated. Delete them.