write-documentation

Write Documentation

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"];
}