How to write technical documentation

Good technical documentation has one job: help users accomplish a goal and get back to work. Style and tone choices either support that goal or get in the way. Clear, consistent writing builds user trust. Inconsistent or unclear writing creates friction and erodes confidence in your product.

This guide covers the core principles behind effective technical writing, with practical guidance on how to apply them.

Write in second personCopy Anchor Link

Address users directly as “you.” Second person makes instructions easier to follow and keeps the focus on what users are doing rather than what the product does.

<!-- Second person (preferred) -->
You can configure the timeout in your settings file.

<!-- Third person (avoid) -->
Users can configure the timeout in the settings file.

Second person also helps expose passive voice: when you write “you,” you’re forced to say who does what.

Use active voiceCopy Anchor Link

Active voice makes sentences shorter and clearer. In passive voice, the subject receives the action. In active voice, the subject performs it.

<!-- Active -->
The API returns an error when the token expires.

<!-- Passive -->
An error is returned when the token has expired.

Passive voice isn’t always wrong. It’s appropriate when the actor is unknown or unimportant. But passive voice as a default habit makes documentation harder to read.

A quick test: if you can add “by zombies” after the verb, the sentence is passive. “An error is returned [by zombies]” is passive. “The API returns [by zombies] an error” is active.

Keep sentences and paragraphs shortCopy Anchor Link

Users scan documentation more than they read it. Long sentences and dense paragraphs slow users down when they’re trying to find a specific answer.

Guidelines:

• Aim for sentences under 25 words
• One idea per sentence
• Two to four sentences per paragraph
• Break up lists of steps with numbered sequences, not run-on prose

If a sentence requires multiple commas or semicolons to hold together, you can probably split it into two sentences.

Use headings that match user intentCopy Anchor Link

Headings organize the page for both humans and search engines. Write them to answer the question a user might have, not to label a topic from the product’s perspective.

<!-- Intent-oriented (better) -->
## How to configure authentication

<!-- Topic label (weaker) -->
## Authentication configuration

Use sentence case for all headings (“Getting started,” not “Getting Started”). Don’t skip heading levels—go from H2 to H3, not H2 to H4.

In Mintlify docs, the page’s H1 generates automatically from the title: frontmatter property. Don’t add a manual H1 in the body.

Use consistent terminologyCopy Anchor Link

Pick one term for each concept and use it everywhere. Switching between “API key,” “API token,” and “access token” to describe the same thing forces users to stop and wonder whether you mean the same thing.

When introducing a term for the first time, define it in place rather than linking away.

<!-- Define in context -->
Each request requires an API key—a unique token that identifies your account.

<!-- Don't assume prior knowledge -->
Each request requires an API key.

If your product has specific names for things (objects, actions, UI elements), use those names exactly as they appear in the product. Capitalize them consistently.

Calibrate tone to your audience and content typeCopy Anchor Link

Tone should match what users are trying to do. A getting started guide for new users benefits from a warmer, more encouraging tone. An API reference for experienced developers benefits from density and precision over warmth.

A few principles that apply across content types:

• Be direct without being terse. “Click Save” is better than “Please click the Save button when you’re ready to proceed.”
• Avoid filler phrases. “It’s worth noting that,” “In order to,” “Please note that,” and “Simply” add words without adding meaning.
• Don’t editorialize. “This is a powerful feature” is an opinion. Document what it does, not how impressive it is.
• Match user vocabulary. If your users call it a “webhook,” don’t call it an “event callback” in the docs. Use the word they’re already searching for.

Avoid common mistakesCopy Anchor Link

Jargon and internal terminologyCopy Anchor Link

Teams develop shorthand that users never encounter. Review new content for terms that would be unfamiliar to someone seeing your product for the first time.

Inconsistent capitalizationCopy Anchor Link

Decide whether to capitalize your product’s feature names (“the Dashboard,” “the API Explorer”) and apply it consistently. Inconsistent capitalization signals lack of attention to detail.

ColloquialismsCopy Anchor Link

Informal phrases and idioms are harder to translate and harder to parse for non-native English speakers. Documentation that reaches an international audience benefits from plain, direct language.

Spelling and grammar errorsCopy Anchor Link

Even a few errors reduce credibility. They signal that no one reviewed the content carefully, which makes users wonder whether the technical content is equally unreliable.

Enforce standards with toolingCopy Anchor Link

Writing principles only stick if they’re part of a repeatable workflow. A few ways to automate enforcement:

• Vale: A linter for prose that checks against configurable style rules. You can write rules that enforce your own terminology, flag passive voice, or catch common mistakes.
• CI checks: Run Vale or other linters on every pull request to catch style issues before content merges.
• Existing style guides: Rather than writing rules from scratch, start from an established guide. The Google Developer Documentation Style Guide, Microsoft Style Guide, and Splunk Style Guide are all free and widely used.

Frequently asked questionsCopy Anchor Link

Related pagesCopy Anchor Link