---
title: How to write technical documentation
description: Voice, sentence length, headings, terminology and tone — the writing rules that make documentation fast to use.
---
Documentation has one job: get the reader to their goal and back to their own work.
Every choice about style and tone either serves that job or gets in its way.
Consistent, clear prose earns trust. Uneven prose makes readers wonder what else was
done carelessly — including the parts they cannot check.
The principles below are the ones that matter most, each with a concrete way to apply
it.
## Write in second person
Talk to the reader as "you". Instructions become easier to follow, and the page stays
focused on what the reader does rather than on what the product is.
```mdx
You can set the timeout in your config file.
Users can set the timeout in the config file.
```
The first line is the one to write. The second puts the reader at arm's length, as if
the page were about someone else.
Second person has a useful side effect: it makes passive constructions harder to hide.
Once the subject is "you", the sentence has to say who does what.
## Use active voice
In active voice the subject performs the action. In passive voice the subject receives
it. Active sentences are shorter and say more.
```mdx
The API returns an error when the token expires.
An error is returned when the token has expired.
```
Passive voice is not forbidden. It is the right choice when the actor is unknown or does
not matter. The problem is passive voice as a habit, where every sentence drifts away
from whoever is actually doing the work.
A quick test: add "by zombies" after the verb. If the sentence still makes sense, it is
passive. "An error is returned by zombies" works, so it is passive. "The API returns by
zombies an error" does not, so it is active.
## Keep sentences and paragraphs short
Readers scan documentation far more than they read it. A long sentence or a dense
paragraph slows down someone who is hunting for one specific answer.
- Keep most sentences under 25 words.
- Put one idea in each sentence.
- Keep paragraphs to two to four sentences.
- Write a sequence of actions as a numbered list, not as a paragraph of prose.
If a sentence needs several commas or a semicolon to hold together, it is usually two
sentences.
## Write headings that match intent
Headings organize the page for readers and for search engines. Write them as the answer
to a question someone actually has, not as a label from the product's point of view.
```mdx
## Configure authentication
## Authentication configuration
```
The first tells the reader what they will do. The second only names a topic.
Use sentence case for every heading: "Getting started", not "Getting Started". Never
skip a level — an `##` is followed by `###`, never by `####`.
In Reed the page's H1 comes from the frontmatter `title`. Do not write one in the body.
`reed check` reports both mistakes — an H1 in the body and a skipped heading level — as
`DS-A02`. See [Pages](/docs/authoring/pages) for the frontmatter rules.
The frontmatter `description` deserves the same care as the headings. It becomes the
meta description, feeds the page's structured data, and is the line that appears next to
the page in `llms.txt`. One plain sentence about what the page lets the reader do is
enough. See [llms.txt and markdown mirrors](/docs/derived/llms-txt).
## Use consistent terminology
Choose one term per concept and use it everywhere. If "API key", "API token" and "access
token" all mean the same thing on your site, every reader has to stop and work out
whether they do.
Define a term the first time it appears, in the sentence where it appears. Do not send
the reader to another page to find out what a word means.
```mdx
Every request needs an API key — a unique token that identifies your account.
Every request needs an API key.
```
The first version works for a reader who has never seen your product. The second assumes
they already know.
When your product names things — objects, actions, settings, screens — use those names
exactly as the product shows them, with the same capitalization every time.
## Match tone to the reader and the page
Tone follows what the reader is trying to do. A first-run tutorial for new users can be
warmer and more encouraging. A reference page for experienced developers should be dense
and precise, not friendly.
Some rules hold everywhere:
- **Be direct, not curt.** "Click **Save**" beats "Please click the Save button when you
are ready to proceed."
- **Cut filler.** "It is worth noting that", "In order to", "Please note that" and
"Simply" add length without adding meaning.
- **Do not editorialize.** "A powerful feature" is an opinion. Say what the feature does
and let the reader judge.
- **Use the reader's vocabulary.** If your users search for "webhook", do not call it an
"event callback". Write the word they are already typing.
## Avoid common mistakes
### Jargon and internal shorthand
Every team develops shorthand its users never see. Read each new page as someone meeting
your product for the first time and flag every term they would not recognize.
### Inconsistent capitalization
Decide whether feature names are capitalized and hold to it. "The Dashboard" on one page
and "the dashboard" on the next looks like nobody was paying attention.
### Colloquialisms
Idioms and casual phrasing are hard to translate and hard to parse for readers who are
not native English speakers. A global audience is best served by plain, literal language.
### Spelling and grammar
A handful of errors costs more credibility than it seems. They suggest nobody reviewed
the page, and a reader who notices will start to doubt the technical content as well.
## Enforce the rules with tooling
A style rule nobody checks is a suggestion. Make the checks part of the workflow that
already runs on every change.
- **`reed check` on every pull request.** It is offline and needs no network, so it runs
in any CI sandbox. It catches the structural half of good writing: a body H1 or a
skipped heading level (`DS-A02`), an image without alt text (`DS-A01`), an unknown
component (`DS-S06`). See [reed check](/docs/reference/cli/check).
- **Design warnings as a gate.** By default, `DS-D*` warnings — such as more than 40
components on one page, or three or more callouts stacked back to back — do not fail
the build. Pass `--strict-components` to make them errors once your pages are clean.
- **A prose linter.** Reed does not check prose. [Vale](https://vale.sh) does: it enforces
configurable style rules, including your own terminology list and passive-voice
warnings. You install and run it yourself, typically as another step in the same CI
job.
- **An existing style guide.** Start from one instead of writing rules from scratch. The
[Google developer documentation style guide](https://developers.google.com/style) and
the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
are free and widely used.
Reed has no scheduled audits or automations. If you want a periodic style sweep, run it
from your CI provider's scheduler.
## Frequently asked questions
As formal as your readers expect, and no more. Documentation for engineers can be
lean: skip pleasantries and get to the code. Documentation for less technical or
enterprise readers often benefits from a warmer tone that anticipates confusion.
Either way, avoid stiff corporate language. "Utilize" is not more precise than "use".
Write the way a knowledgeable colleague explains something, not the way a contract
describes it.
When the actor is unknown or irrelevant, or when the result matters more than who
caused it. "The request is validated before processing" is fine if the page is about
what happens to a request. Passive voice becomes a problem when it hides who has to
act — especially when that someone is the reader.
Pick the primary reader for each page and write for them. A getting-started page
assumes little. A reference page assumes the reader knows the domain. Trying to
serve both in one page fails both: beginner context slows experts down, and expert
shorthand loses beginners. If you truly have two audiences, give them different pages
of different types — see Documentation content types.
Keep a terminology list: a short table of preferred terms and the terms they replace.
Share it with everyone who writes docs and check it during review. A prose linter
such as Vale can enforce it automatically from a vocabulary file. The list pays for
itself quickly in shorter reviews and fewer confused readers.
Long enough to cover its one topic, short enough to stay on it. A page that covers two
tasks should usually be two pages. A page that covers one task but feels thin is
probably missing detail. Reference pages can be long and dense because readers scan
them. Explanation pages should be shorter because readers read them.
## Related pages
Match each page to what the reader needs in the moment.
Find out who you are writing for before you write.
Make every page usable by more readers.
Help readers find the page in the first place.