> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/guides/llms.txt
> Use this file to discover all available pages before exploring further.

# Style and tone

> Principles for style and tone

<Tip>
  In this article, you'll learn about stylistic choices, common pitfalls, and practical implementation tips for writing technical documentation.
</Tip>

## Writing principles

* **Be concise**: People aren't reading docs for fun; they want to achieve a goal. Cut all unnecessary words.
* **Clarity over cleverness**: Be simple, direct, and avoid jargon or complex sentence structure.
* **Use active voice**: Instead of saying "A configuration file should be created," use "Create a configuration file."
* **Be skimmable**: Use headlines to orient structure. Break up text-heavy paragraphs.
* **Write in second person**: Referring to your reader makes it feel like the documentation is written for them.

## Common writing mistakes

* **Don't have spelling and grammar mistakes**: Grammatical errors may seem small, but they're a key indicator of quality. They can degrade trust in your product as well.
* **Avoid inconsistency in terminology**: Calling something an "API key" in one paragraph then "API token" in the next makes it much more difficult for users.

> Consistency is key! You may not be complimented on your consistency, but people will absolutely notice and be frustrated by a lack thereof.
>
> \- **CT Smith, Head of Docs at Payabli**

* **Don't use product-centric terminology**: Your users don't have the full context of your product (see [Understand your audience](/know-your-audience)). Always orient language around the user's familiarity with your product and what they're trying to achieve.
* **Avoid "duh" documentation**: Don't tell users "Click Save to save." Documentation should add value, not outline obvious steps.
* **No colloquialisms**: Especially for localization, colloquialisms hurt clarity.

## Tips for enforcing style

Leverage existing style guides to standardize your documentation:

* [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
* [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse)
* [Google Developer Documentation Style Guide](https://developers.google.com/style)

When you know which writing principles you want to implement, automate as much as you can. You can use linters like [Vale](https://vale.sh) or your documentation provider, such as Mintlify's [CI checks](https://mintlify.com/docs/settings/ci).