Writing Technical Docs

Writing technical docs

Overview

Technical writing runs through almost every development task: the README, the PR description, the doc comment, the design doc. This skill provides a repeatable writing process — audience, gather, structure, draft, review — whose depth scales with the doc, plus reference docs to consult for specific questions.

The scale rule: size every step of the process to the doc. A doc-block comment has a conventional structure and needs no outline; a one-line review comment needs no review checklist; an engineering blog post or design doc earns the full loop. When in doubt, do less — but the review step scales down, never to zero.

Not for: authoring skills (slow-powers:writing-skills owns the skill doc type and takes precedence; see Related skills), or non-documentation replies (chat answers, status updates).

Step 0: decide the audience and style

Before writing, decide who reads this and what register fits. This decision is the metric every later choice is checked against — structure, depth, terminology, tone. One line of thought for a comment; an explicit audience sentence near the top of a long doc. doc-types.md lists per-type audience and structure defaults; use them when the doc matches a type.

The process

flowchart TD
    start([Doc to write]) --> audience[Decide audience<br/>and style]
    audience --> gather[Gather only what<br/>the doc needs]
    gather --> structure{Conventional structure<br/>for this doc type?}
    structure -->|yes| use[Use it — done deciding]
    structure -->|no| outline[Outline; split large docs into<br/>self-contained sections]
    use --> draft[Draft for the audience,<br/>evergreen]
    outline --> draft
    draft --> review{Doc size?}
    review -->|small| spot[Reread once: evergreen,<br/>right for the reader]
    review -->|large| full[Review checklist +<br/>reference docs]
    spot --> done([Hand off])
    full --> findings{Actionable findings?}
    findings -->|yes| draft
    findings -->|no| done

Gather information

The goal is a good doc, not a thorough investigation. Collect only what the doc needs:

• Reuse what the session already established; don't re-verify confirmed facts or re-read code you just wrote.
• Verify the specific claims the doc will make — no more. If gathering starts to feel like its own research project, stop and write what you know; note genuine open questions in the draft instead.

Structure the doc

• First check doc-types.md: if the doc matches a type, its conventional structure applies and this step is done. A doc-block comment has an exact structure; there is nothing extra to consider.
• For a large doc, write the outline and treat each section as its own small doc — the process applies recursively: each section makes sense alone, and together they make sense combined.

Draft

This is the step where the skill has the least to say — you already write well. Two orientations, held as spirit, not boxes to tick:

• Write for the step-0 audience. Depth, terms, and tone follow from who reads it. When a choice is hard, re-ask the audience question.
• Write evergreen. Describe the system or topic as it is, not the session that produced the text: no "now supports", "currently", "the new parser", "I moved this into utils.ts". Assume the output lives for months; justify exceptions (release notes, changelogs) rather than assuming them. The word list and exceptions live in style-principles.md — skim it once, don't memorize it.

Review the draft

Review always happens; only its depth scales. A comment or one-paragraph doc gets a single reread through two lenses — is it evergreen? and is it right for this reader? A substantial doc (a page or more) earns the checklist:

- [ ] Audience and style: every section serves the reader decided in step 0; depth
      and terminology match what they know
- [ ] Evergreen: no time-anchored words ("now", "currently", "new", "soon"), no
      session narration, no promises of future features
- [ ] Claims: every performance, cost, or security claim is verifiable and sourced;
      no superlatives or guarantees
- [ ] Structure: follows the doc-type convention; headings nest without gaps; each
      section stands alone
- [ ] Formatting: code, commands, placeholders, lists, tables, and notices verified
      against references/formatting.md
- [ ] Links: each one necessary, descriptive, and resolving

Copy the checklist into your persistent task tracker when it applies. Judge each item — a real "not applicable" is a pass, a shrug is not. Keep findings actionable and verifiable: fix it or consciously drop it, but no open-ended style debates and no back-and-forth over taste.

The reference docs are review-time and lookup tools, not pre-draft reading. Open formatting.md when a content type appears in the doc; open style-principles.md to ground a style decision or a review finding. Consult the online source guides only for details that may have changed since these references were distilled.

Failure modes — both directions

Reference docs

Related skills

• slow-powers:writing-skills — the doc-type authority for skills: it owns skill structure, frontmatter, and skill-specific prose conventions (descriptions, rationalization-proofing, discipline framing). When writing a skill, this skill's style principles still govern the prose where writing-skills is silent — on any conflict, writing-skills takes precedence.
• slow-powers:verifying-development-work — owns the review pass before handing back code changes; its comment-hygiene checks defer to this skill's evergreen rules.