How to write technical documentation

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 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.

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.
• 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 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 and the Microsoft Writing Style Guide 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

How formal should technical documentation be?

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 is passive voice acceptable?

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.

Should I write for beginners or experts?

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.

How do I keep terminology consistent across a large site?

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.

How long should a documentation page be?

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

Documentation content types

Match each page to what the reader needs in the moment.

Understand your audience

Find out who you are writing for before you write.

Accessibility

Make every page usable by more readers.

SEO

Help readers find the page in the first place.