/write-documentation

name: write-documentation
description: "Use when writing or substantially rewriting human-facing prose: documentation, README, guides, blog posts, emails, Slack messages, PR descriptions, release notes, or any text a human will read. Not for code comments, commit messages, or agent-to-agent communication."

Write Documentation

<!-- Adapted from Anbeeld/WRITING.md v1.3.1 (MIT). Attribution: README "Built on"; version pin: CLAUDE.md Upstream Sources. -->

**Announce at start:** "I'm using the write-documentation skill to write human-quality prose."

Purpose

Write for the actual context.

The goal is prose that fits the medium, the task, and the reader. If it does that well, it will usually read as human-authored as a side effect. Do not optimize for "sounding human." Do not optimize for beating detectors. Both produce worse writing.

When to Use

• Writing or substantially rewriting any human-facing text
• Creating documentation from scratch (README, guides, tutorials, API docs)
• Drafting blog posts, articles, emails, or Slack messages
• Rewriting a section flagged by `document-release` as needing major revision
• User asks for help with prose quality, tone, or style
• Writing PR descriptions, release notes, or CHANGELOG entries

When NOT to Use

• Code comments and docstrings (for developers reading code)
• Commit messages (their own conventions)
• Agent prompts, skill files, CLAUDE.md (for AI agents, not human readers)
• Minor edits: fixing a typo, updating a version number, adding a link
• `document-release` work that is factual syncing, not prose rewriting

Beads Integration

bd create "Write: <description of what's being written>" -t task

Closed with evidence at Step 6 — the single source of truth for the close command.

Core Workflow

digraph write_documentation {
    rankdir=TB;
    node [shape=box, style=rounded];

    context [label="Step 1: Identify Context\nMedium, audience, reader need, register"];
    structure [label="Step 2: Structure Decision\nTask-oriented → answer first\nLong-form → through-line + example"];
    draft [label="Step 3: Draft\nRules internalized, not mechanical\nFocus on substance"];
    checks [label="Step 4: Required Checks\nShort: 1-3, 5, 7, 10\nLong: all 1-10"];
    cut [label="Step 5: Cut\nGeneric, ceremonial, over-engineered"];
    present [label="Step 6: Present to User"];
    revise [label="User requests changes?" shape=diamond];
    done [label="Close bead with evidence" shape=doublecircle];

    context -> structure -> draft -> checks -> cut -> present -> revise;
    revise -> draft [label="yes"];
    revise -> done [label="no"];
}

Step 1: Identify Context

Before writing anything, answer these four questions:

1. **What is this text?** (medium: README, email, blog post, Slack message, guide, PR description...) 2. **Who reads it?** (developers, end users, managers, the public...) 3. **What do they need?** (an answer, a next action, understanding, a decision...) 4. **What register?** (formal technical docs, casual chat, professional email, marketing...)

Done when: all four questions have explicit answers.

Step 2: Structure Decision

• **Task-oriented text:** Identify the answer or next action that belongs first.
• **Long-form text:** Decide the through-line and one concrete example, moment, or case that can carry real weight in the piece.
• Apply medium routing (see below).

Done when: the answer/next-action (task-oriented) or through-line-plus-example (long-form) is decided, and medium routing is applied.

Step 3: Draft

Draft to fit the identified context, not an abstract idea of "good writing." The core rules below should be internalized during drafting, not mechanically applied paragraph by paragraph. Focus on substance over style.

Done when: a complete draft exists covering the identified context.

Step 4: Required Checks

Run the revision checks scaled to the length and stakes of the piece. Fix issues inline during this pass. See the Required Checks section below.

Done when: the scaled check set has been run and every issue it found is fixed inline.

Step 5: Cut

Cut what sounds generic, ceremonial, over-engineered, suspiciously over-specific, or too cleanly modular. Collapse paragraphs that restate each other. Replace the most generic clause in the piece with something specific or delete it.

Done when: the piece has been reviewed for generic/ceremonial language and the most generic clause is fixed or gone.

Step 6: Present to User

Show the final text. If the user requests changes, loop back to Step 3. When approved, close the bead: `bd close <id> --reason "Written: <what>, checks run: <which checks passed>"`.

Done when: the user has approved the text and the bead is closed with evidence of which checks ran.

Precedence

When rules conflict:

1. Truth, safety, accessibility, and platform/legal requirements 2. Explicit user instructions 3. Genre and medium norms 4. Core rules 5. Optional watchlists and heuristics

If the user asks for bullets, use bullets. If accessibility or the medium require structure, use structure. If the user asks for a neutral summary, do not force first person or extra stance into it.

Medium Routing

• **Chat, comments, replies, DMs, forum posts:** Running prose by default. Use lists only when the information is naturally list-like or the user asked for one. Avoid decorative formatting and canned support tone. In plain-text contexts, prefer straight ASCII quotes and apostrophes. Prefer commas, colons, conjunctions, subordinate clauses, or full stops over em dashes unless the dash clearly earns its keep. Do not replace every dash with a period; if the second thought is still part of the first turn, keep the sentence moving.
• **Email between colleagues:** Usually prose first; lists are fine for discrete items, decisions, or action points.
• **Documents, specs, reports, technical writing:** Structure is expected. Use headings, bulle