Technical Writing skill for Claude Code

A document is done when a named reader with a named goal can reach that goal using only the page, every code sample runs as written, and nothing on the page serves a different reader or goal. Clear technical writing is mostly decisions about what to leave out.

Ground rules

• Name the reader and their goal before writing a word. “Backend engineers integrating webhooks for the first time, who want a verified test event in 15 minutes.”
• One document, one Diátaxis type. Mixing a tutorial with reference tables and design rationale produces a page that serves nobody.
• Lead with the answer or the outcome. Background goes after, or in a linked page.
• Every claim a reader will act on has an example. Every example is copy-pasteable and has been run.
• Prefer the reader’s words (from support tickets, search terms, error messages) over internal names.

Pick the document type

Reader is…	They need	Type	Shape
New, learning by doing	A guaranteed first success	Tutorial	Linear steps, one path, no choices, visible result at each step
Competent, has a specific task	Steps to accomplish it	How-to guide	Goal-titled (“How to rotate API keys”), prerequisites, steps, verification
Working, needs a fact	Accurate, complete, scannable info	Reference	Consistent structure per item, tables, no narrative
Curious, wants to understand	Context, reasons, trade-offs	Explanation	Prose, diagrams, alternatives considered

For the full Diátaxis guidance with examples of each type and how to split a mixed page, read references/diataxis.md when restructuring existing docs or when unsure which type a page should be.

Workflow

- [ ] 1. Write the reader/goal statement and pick the type
- [ ] 2. Outline as headings that read like a table of contents for the task
- [ ] 3. Draft fast, examples first
- [ ] 4. Run every command and code sample; paste real output
- [ ] 5. Edit: cut, restructure, simplify sentences
- [ ] 6. Test against the reader's goal; lint

1. Reader/goal statement

Reader: <role, what they already know, what they don't>
Goal: <what they can do after reading>
Type: tutorial | how-to | reference | explanation
Out of scope: <what this page deliberately does not cover, with links>

Keep it at the top of the draft; delete before publishing (or keep as the page intro if it reads naturally).

2. Outline

• Headings are tasks or questions: “Create a webhook endpoint”, “Verify signatures”, not “Overview”, “Details”, “Miscellaneous”.
• Order by the reader’s sequence, not by system architecture.
• Prerequisites at the top as a checklist with versions: “Node.js 20+, an API key with webhooks:write scope”.

3. Draft: sentence and paragraph rules

Rule	Before	After
Active voice, name the actor	“The token is validated.”	“The gateway validates the token.”
Imperative for instructions	“You will want to run the migration.”	“Run the migration.”
One idea per sentence	“Set the env var, which is read on boot, unless you use the config file, in which case…”	“Set API_URL. The server reads it at startup. If you use config.toml, set api_url there instead.”
Specific over vague	“It may take some time.”	“The first build takes about 4 minutes.”
Condition before instruction	“Click Save if you changed the region.”	“If you changed the region, click Save.”
No hedging filler	“Basically, you just simply need to…”	“Run…”
Define on first use	“Configure the DLQ.”	“Configure the dead-letter queue (DLQ), where failed messages go.”

Paragraphs: 1–4 sentences. Sentences: aim for an average under 20–25 words; split any over 35.

Words to cut on sight: simply, just, easily, obviously, of course, basically, very, in order to (→ to), utilize (→ use), leverage (→ use), please note that.

Code samples

• Show the complete, runnable unit: imports, variables defined, realistic values.
• Mark placeholders visibly and consistently: <YOUR_API_KEY> or $API_KEY, and say where to get the value.
• Show expected output right after the command.
• Use language tags on every fenced block; separate commands from output.
• Prefer one canonical example over three variants; link to alternatives.

curl -s https://api.example.com/v1/events \
  -H "Authorization: Bearer $API_KEY"

{ "data": [{ "id": "evt_123", "type": "invoice.paid" }], "has_more": false }

Formatting

• Numbered lists for sequences; bullets for unordered sets; tables for comparisons of 3+ items across 2+ attributes.
• Admonitions sparingly: one warning per real risk (data loss, security, cost). If every paragraph has a callout, none are read.
• Bold for UI labels the reader clicks (Settings → API keys); code font for anything typed or read from a terminal.
• Diagrams when relationships matter more than sequence (see mermaid-diagrams).

5. Edit passes

Run separate passes; each looks for one thing:

1. Structure: does the order match the task? Is anything for a different reader?
2. Cut: remove intros that restate the title, repeated warnings, history nobody needs. Target 20–30% shorter than the first draft.
3. Sentences: voice, length, vague words.
4. Consistency: one term per concept, same placeholder style, same heading grammar.
5. Accuracy: rerun the examples after edits.

For a deep line edit, use prose-editing.

6. Test

• Reader-goal test: follow the doc in a clean environment (fresh container, new account) exactly as written. Every deviation you had to make is a bug in the doc.
• Skim test: read only headings and the first sentence of each section; the reader should still know what to do.
• Lint with Vale if the repo has it (vale docs/), markdownlint (npx markdownlint-cli2 "docs/**/*.md"), and a link checker (lychee docs/).

Gotchas

• Writing for yourself: skipping steps you do automatically (activating a venv, exporting an env var, being logged in).
• Screenshots go stale fastest; use them for orientation only and describe the UI path in text too.
• “Simple”/“easy” insults readers who are stuck and adds no information.
• Version drift: state the version the doc was tested against (“Tested with v3.2, October 2026”).
• Future tense and hypotheticals (“this will allow you to”) hide the actual instruction.
• Explaining design rationale inside step 4 of a how-to derails the reader; link to an explanation page.

Output contract

# <Task-oriented title>

<One or two sentences: what the reader will accomplish and how long it takes.>

## Prerequisites
- ...

## <Step-group heading>
1. ...
   ```bash
   ...
   ```
   Expected output: ...

## Verify it worked
...

## Next steps
- <links to related how-tos, reference, explanation>