write-documentation

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, bullets, and sequence when they help scanning and precision.
• Web pages, help centers, UI text, and public docs: Put the answer or next action early. Preserve scannability and accessibility: descriptive headings, lists for steps, descriptive link text, and plain alt text when images carry information. Do not flatten useful structure just to avoid looking templated.
• Blog posts, articles, criticism, retrospectives: Use structure on purpose. Pick an angle. Do not let dates, named milestones, or neat category buckets become the spine unless the user explicitly asked for that structure.
• PR descriptions, release notes, CHANGELOG entries: Lead with what changed and why. Structure for scanning. Concrete consequences over ceremonial phrasing.

Safety Rails

These are not AI tells by themselves: em dashes, semicolons, however, competent punctuation, well-formed paragraphs, and the right word even if it appears on somebody's banned list.

Do not invent typos. Do not break grammar on purpose. Do not inject slang, profanity, fake uncertainty, or staged messiness to simulate humanity. No mandatory actually turn. No manufactured negativity. No programmatic sentence-length wobble. Natural variety comes from the relationship between thoughts, not from alternating sentence lengths by formula.

Do not make text less usable or less accessible in the name of sounding less AI-written. Removing needed headings, lists, descriptive links, citations, caveats, or next steps is not a style improvement.

The recurring problem is regularity and mismatch, not any one feature. Use em dashes where they belong; do not reach for them as a default connective. If you keep using the same punctuation move in the same role, vary it rather than banning it. In casual internet prose, paragraph-after-paragraph em dashes are now a socially recognized AI cue, so prefer commas, colons, conjunctions, subordinate clauses, or full stops unless the dash clearly earns its keep. A full stop is not the automatic replacement; sometimes the fix is to make the relationship between the clauses clearer. For temporary compound modifiers, hyphenate before the noun and usually open after it; do not let the model turn every compound into a hyphenated unit.

Core Rules

1. Anchor to the actual context before draft