Technical Writing

Technical writing

You write the document a person reads to use a product or codebase: a README, a tutorial, a how-to, API/CLI/config reference. Not marketing prose, not an SEO article, not a course. The craft is mostly one decision made early and held: what kind of doc does this reader actually need, then writing that one kind in its correct shape.

The backbone is Diátaxis — four documentation modes, each serving a distinct need (diataxis.fr). The sentence-level rules come from the Google developer documentation style guide (developers.google.com/style). The shipping discipline is docs-as-code: docs live with the code and lint in CI.

First move: classify the doc

Before you write a line, name the reader's need and pick exactly one mode. Mixing modes in one page is the single biggest reason docs fail readers — the learner gets buried in parameters, the expert wades through a beginner tutorial to find one flag.

Rule: one page, one mode. Why: a tutorial answers "how do I start?", reference answers "what are the flags?" — a reader arrives with one question, and a page serving two answers neither well.

If a page already mixes modes, do not patch it — split it. See references/diataxis-modes.md for a worked split of one bad page into four.

Tutorial

A lesson a beginner runs end to end and succeeds. You are the instructor; their success is your responsibility, not theirs.

• Title it for the learner's gain: "Build your first X", not "X configuration".
• State prerequisites and exact versions up top before step 1.
• Number every step. Each step produces a visible result the reader can check against.
• It must run start-to-finish on a clean machine. Test it on one.
• No branching. No "if you prefer Y…", no "depending on your setup". One path.
• No explanation of why. A learner doing 12 new things cannot also absorb design rationale. Link the "why" to an explanation page.

Bad → Good opening:

<!-- Bad: assumes context, branches, explains -->
Depending on your package manager, install the SDK (we use a monorepo
because it scales better). Configure your environment as needed.

<!-- Good: one path, concrete, checkable -->
## Build your first report

You need Python 3.12+ and a free API key from example.com/keys.

1. Install the SDK:
   ```bash
   pip install acme-sdk==4.2.0

2. Save your key:

   export ACME_KEY="your-key-here"
   

   Run echo $ACME_KEY — you should see your key printed back.

## How-to

A recipe for someone who already knows the product and has a real goal right now.

- Title it as the goal: **"How to rotate an API key"**, not "API keys".
- Assume competence. Do not re-teach concepts; link to reference/explanation instead.
- Ordered steps, but the reader may adapt — state the goal so they can.
- Address one real-world task. "How to configure logging" is reference; "How to ship logs to Datadog" is a how-to.
- No tutorial hand-holding, no narrative.

Bad → Good:

```md
<!-- Bad: teaches, no clear goal in the title -->
## Logging
Logging is important. A logger has levels: DEBUG, INFO… Here is how
levels work, and then some setup.

<!-- Good: goal title, competent reader, straight to it -->
## How to send logs to Datadog
1. Set `LOG_SINK=datadog` and `DD_API_KEY` in the environment.
2. Restart the worker: `acme worker restart`.
3. Confirm delivery in Datadog → Logs within ~1 min.

Reference

The technical facts, structured to mirror the product. The reader is not reading top to bottom — they are scanning for one entry.

• Dry, complete, consistent. Same structure for every entry.
• Structure follows the code: one section per command, endpoint, or config key.
• Use tables for parameters, flags, return values, and errors.
• No opinions, no recommendations, no "you should". Reference states what is. Move "which one to pick" to a how-to or explanation.
• Document every parameter, including defaults and required/optional.

### `GET /reports/{id}`

| Param | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes | Report identifier. |
| `fields` | query | string | no | Comma-separated fields to return. Default: all. |

**Responses**

| Status | Meaning |
|---|---|
| `200` | Report returned. |
| `404` | No report with that `id`. |
| `429` | Rate limit exceeded; retry after `Retry-After` seconds. |

Explanation

Background and the "why" — context, design decisions, trade-offs, alternatives considered.

• Discursive prose, free to make connections and admit nuance.
• Never numbered steps. If you are writing "1. … 2. …", it is a tutorial or how-to, not an explanation.
• Free to hold an opinion and explain the reasoning — this is the only mode where opinion belongs.
• Title with "About…", "Why…", or a concept name. Read at leisure, not while doing.

README recipe

The one doc everyone gets wrong by turning it into a pitch. A README lives in the top-level directory, orients a new reader, and at minimum says what the thing is, what it is for, and links to fuller docs (Google docguide).

Skeleton, in order: what + why (two lines) → install → one minimal runnable example → link to deeper docs → status/license.

Bad → Good opening lines:

<!-- Bad: a sales page -->
# Acme SDK 🚀
The most powerful, blazing-fast, developer-friendly toolkit to
effortlessly supercharge your data workflows!

<!-- Good: what it is, what it's for, in two lines -->
# Acme SDK
A Python client for the Acme reporting API. Fetch, filter, and export
reports without writing HTTP by hand.

## Install
```bash
pip install acme-sdk==4.2.0

## Sentence-level rules

Apply these to every mode. Each ships clearer prose at no cost.

| Rule | Why | Bad → Good |
|---|---|---|
| Second person, imperative steps | The reader is *doing* this | "The user should run…" → "Run…" |
| Active voice | Names who acts | "The file is created by the script" → "The script creates the file" |
| Present tense | Docs describe how it works now | "This will return a list" → "This returns a list" |
| Define before use | No forward references | Spell out a term the first time, then use it |
| One idea per sentence | Scannable, translatable | Split the 40-word sentence into two |
| Cut "in order to" | It is always just "to" | "in order to deploy" → "to deploy" |
| Ban weasel/AI-tell words | They lie about difficulty and add nothing | "simply run X" → "run X" |

Banned words: **simply, just, easy, effortless, seamless, robust, powerful, leverage, utilize, in order to, blazing-fast, supercharge**. If a step is "simple", the reader either already knows it (delete the word) or does not (the word mocks them). Full banlist with replacements is in `references/diataxis-modes.md`.

## Code examples

- Minimal: the fewest lines that work. Cut every line not required to run.
- Runnable and **tested** — copy-paste it onto a clean machine and confirm. Untested samples rot and misinform.
- Language-tag every fence (`bash`, `python`, `json`, `yaml`, `ini`).
- Show expected output so the reader knows they succeeded.
- No `...` standing in for required lines. Elide only genuinely irrelevant detail, and say so.

```python
# Good: minimal, runnable, shows what comes back
from acme import Client

client = Client(api_key="your-key")
report = client.reports.get("3f9a-...")
print(report.title)
# -> "Q2 revenue"

Docs-as-code

Treat docs like code, or they go stale and mislead.

• Change docs in the same PR as the code they describe. Dead docs are worse than no docs — they actively misinform and slow developers (Google docguide best practices).
• Lint prose in CI. Vale is the de-facto open-source prose linter: config in .vale.ini at the repo root, custom rules in a styles dir, run as a blocking check on every PR touching Markdown. Common rules ban "simply/just/easy" and enforce "sign in" over "log in". Used in production by GitLab, Datadog, and ING.
• Test samples and check links in CI (writethedocs.org). A broken pip install line in a tutorial breaks every reader.

A starter .vale.ini, a custom banned-terms style, and a GitHub Actions blocking job are in references/vale-starter.md.

Anti-patterns

Before you ship

• Page is exactly one Diátaxis mode (tutorial / how-to / reference / explanation).
• Prerequisites and versions are stated before step 1 (tutorial/how-to).
• Every code sample runs on a clean machine and shows expected output.
• No ... hides a line the reader needs.
• Banlist is clean (scripts/verify.sh path/to/doc.md).
• All links resolve.
• README says what it is + what it's for + links to deeper docs.
• Doc changed in the same PR as the code it documents.

References

• references/diataxis-modes.md — per-mode templates, a worked split of one mixed page into four, and the full weasel-word/AI-tell banlist with replacements.
• references/vale-starter.md — starter .vale.ini, a custom banned-terms Vale style, and a GitHub Actions job running Vale as a blocking check.

Siblings

• SEO blog post / long-form article with schema and FAQ → ../article-writing/SKILL.md.
• Editorial calendar, pillars, content pipeline → ../content-engine/SKILL.md.
• Teaching a syllabus over time with narrative → ../course-storytelling/SKILL.md.
• Brand tone and voice rules → ../brand-voice/SKILL.md.
• Making docs and samples accessible → ../accessibility/SKILL.md.
• Localizing finished docs into another language → translation-l10n.