documentation-writer

Files (1)

• SKILL.md

SKILL.md (first lines)

# /documentation-writer — Human-Facing Documentation

Documentation fails in two directions: it does not answer the question the
reader arrived with, or it answers it somewhere the reader never looks. Most of
the work is deciding what kind of document you are writing and who is reading
it, before writing a line.

## Identify the document before writing it

Readers arrive with one of four questions. Mixing the answers into one page is
the most common documentation failure — a tutorial interrupted by API tables
serves neither reader.

| Reader's question | Document type | Shape |
| --- | --- | --- |
| "Get me to a first success" | Tutorial / quickstart | Ordered steps, one path, no options |
| "How do I accomplish X?" | How-to guide | Task-titled, assumes basics, may branch |
| "What are the exact parameters?" | Reference | Complete, structured, alphabetical or grouped |
| "Why is it built this way?" | Explanation / ADR | Prose, trade-offs, alternatives rejected |

If a page is trying to be two of these, split it and cross-link.

## Write for scanning

Readers scan before they read. Every structural choice should reward a reader
who only looks at headings and the first line of each section.

- **Headings state the answer, not the topic.** "Run migrations before starting
  the server" beats "Migrations."
- **Front-load.** The first sentence of a section carries its conclusion; the
  rest supports it.
- **One idea per paragraph**, and prefer a table or list when the content is
  genuinely parallel — but not when it is prose wearing a list costume.
- **Link out instead of inlining depth.** Name what is on the other side of the
  link so the reader can judge whether to follow it.

Length follows the content. A README for a small tool may be thirty lines; a
reference page may be five hundred. There is no target word count — the test is
whether a reader can find their answer, not how long the page is.

## Examples must run

Copy-pasteable examples are the highest-value content in most documentation,
and wrong ones are the highest-cost.

- Show real commands and real output, not placeholders the reader must decode.
- Verify examples against the current code before publishing. If you cannot run
  it, say what version it was checked against.
- Prefer a complete small example over a fragment with elisions.
- Include the failure case when it is common — the error message a reader will
  paste into a search box is worth documenting verbatim.

## Put information where it will be found

The right location beats the right words. Before writing, check whether the
information already lives somewhere and is simply stale.

- **README** — what this is, who it is for, how to run it, where to go next.
  Not a manual.
- **Code comments** — why this line is surprising. Never what the line does.
- **`CLAUDE.md`** — the conventions an agent must hold to work in this repo.
  Keep it short; it loads on every session.
- **Reference docs next to the code they describe**, so a change and its
  documentation land in the same diff.
- **Changelog / release notes** — what changed for a consumer, in their terms,
  not commit subjects.

Duplicating content across locations guarantees divergence. Pick one home and
link to it.

## Keep it from rotting

Stale documentation is worse than none, because readers trust it.

- Avoid time-relative phrasing — "currently", "new", "recently", "for now",
  "the upcoming release". Write what is true, or date the claim.
- Do not document unreleased or intended behavior as if it exists.
- When you change behavior, grep for the old behavior in the docs in the same
  change.
- Prefer generated reference material (CLI `--help`, schema dumps) over
  hand-maintained tables that will drift.
- If you find documentation that is wrong, fix it or delete it. Leaving it with
  a caveat is the worst of the three options.

## Voice

- Second person and active voice: "run the migration", not "the migration
  should be run."
- Present tense for behavior: "the hook blocks the commit."
- Define a term once, then use exactly that term — synonyms read as new
  concepts.
- Say what a thing does before saying what it is called.
- Cut hedges ("simply", "just", "of course", "obviously"). They add nothing and
  make a stuck reader feel worse.

## Before you ship

- Does the first paragraph tell a stranger whether this page is for them?
- Can a reader who skims only the headings get the gist?
- Does every command and code block run as written?
- Is anything here duplicated from another document?
- Would this still be correct in six months, or does it need a date?

## Related

- `/skill-writer` — SKILL.md and agent files, which have different constraints
  (they load into a model's context and carry frontmatter contracts)
- `CLAUDE.md` — this project's own conventions

From dougborg/harness-kit, Apache-2.0.

More from dougborg/harness-kit