mintlify__docs/guides/style-and-tone.mdx

---
title: "How to write technical documentation"
sidebarTitle: "Style and tone"
description: "Write clear, consistent technical documentation with practical guidance on voice, structure, terminology, and tone for developer and product docs."
keywords: ["technical writing", "documentation style guide", "writing standards", "voice and tone", "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 person

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.

```mdx
<!-- 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 voice

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

```mdx
<!-- 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.

{/* vale Mintlify.Passive = NO */}

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.

{/* vale Mintlify.Passive = YES */}

## Keep sentences and paragraphs short

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 intent

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.

```mdx
<!-- 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 terminology

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.

```mdx
<!-- 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 type

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 mistakes

### Jargon and internal terminology

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 capitalization

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.

### Colloquialisms

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 errors

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 tooling

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

- **[Vale](https://vale.sh):** 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](/deploy/ci):** 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](https://developers.google.com/style), [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/), and [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse) are all free and widely used.

<Tip>
  Use an [automation](/automations) to run a style audit on a schedule or whenever changes push to your docs repository.
</Tip>

## Frequently asked questions

<AccordionGroup>
<Accordion title="How formal should technical documentation be?">
Match the formality to your audience and product context. Developer tools for engineers can be direct and lean—skip pleasantries and get to the code. Documentation for less technical users or enterprise products often benefits from a warmer tone that anticipates confusion. Either way, avoid stiff corporate language. "Utilize" doesn't add precision over "use." Write the way a knowledgeable colleague would explain something, not the way a legal document would describe it.
</Accordion>

<Accordion title="When is passive voice acceptable?">
{/* vale Mintlify.Passive = NO */}

When the actor is unknown, irrelevant, or when emphasizing the result is more important than who causes it. "The request is validated before processing" is fine if you're describing what happens to a request, not who validates it. Passive voice becomes a problem when it obscures who is responsible for an action the user needs to take.

{/* vale Mintlify.Passive = YES */}
</Accordion>

<Accordion title="Should I write for beginners or experts?">
Identify the primary audience for each page and write for them. A getting started guide should assume minimal prior knowledge. An API reference should assume the reader knows how APIs work. The mistake is trying to serve both in the same page—adding beginner context to a reference page slows experts down, and assuming expert knowledge in a tutorial loses beginners. If you genuinely have two distinct audiences, consider separate content types for each. See [Content types](/guides/content-types) for guidance.
</Accordion>

<Accordion title="How do I keep terminology consistent across a large documentation site?">
Maintain a terminology list—a simple table of preferred terms and terms to avoid. Share it with everyone who contributes to docs and check it during review. Vale can enforce it automatically with a custom vocabulary file. The investment in maintaining a list pays off quickly in reduced review cycles and fewer user complaints about confusing terminology.
</Accordion>

<Accordion title="What's the right length for a documentation page?">
Long enough to cover the topic completely, short enough to stay focused. If a page covers two distinct tasks, consider splitting it. If it covers one task but the content is thin, it may be missing important detail. Reference content can be long and dense—users scan it. Conceptual content should be shorter—users read it. See [Content types](/guides/content-types) for more on matching page length to content purpose.
</Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Content types" icon="folder-tree" href="/guides/content-types">
    Choose the right content type for your documentation goals.
  </Card>
  <Card title="Accessibility" icon="person-standing" href="/guides/accessibility">
    Make your documentation accessible to more users.
  </Card>
  <Card title="Format text" icon="case-sensitive" href="/create/text">
    Learn text formatting and styling options.
  </Card>
  <Card title="SEO best practices" icon="search" href="/guides/seo">
    Improve documentation discoverability.
  </Card>
</CardGroup>