mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
287d71a8c2
* Update guides/index.mdx * Update guides/accessibility.mdx * Update guides/media.mdx * Update guides/style-and-tone.mdx --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
52 lines
2.6 KiB
Plaintext
52 lines
2.6 KiB
Plaintext
---
|
|
title: "Style and tone"
|
|
description: "Write effective technical documentation with consistent style."
|
|
keywords: ["writing principles", "active voice", "technical writing", "style guides"]
|
|
---
|
|
|
|
<Tip>
|
|
This page explains stylistic choices, common mistakes, and implementation tips for writing technical documentation.
|
|
</Tip>
|
|
|
|
## Writing principles
|
|
|
|
- **Be concise.** People are reading documentation to achieve a goal. Get to the point quickly.
|
|
- **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 readers. Break up text-heavy paragraphs. Use bullet points and lists to make it easier to scan.
|
|
- **Write in second person.** Referring to your reader makes it easier to follow instructions and makes the documentation feel more personal.
|
|
|
|
## Common writing mistakes
|
|
|
|
- **Spelling and grammar mistakes.** Even a few spelling and grammar mistakes in your documentation make it less credible and harder to read.
|
|
- **Inconsistent terminology.** Calling something an “API key” in one paragraph then “API token” in the next makes it difficult for users to follow along.
|
|
- **Product-centric terminology.** Your users don't have the full context of your product. Use language that your users are familiar with.
|
|
- **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 [CI checks](/deploy/ci) or linters like [Vale](https://vale.sh).
|
|
|
|
## 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>
|