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