Pular para o conteúdo principal

​
Style and tone

Write effective technical documentation with consistent style.
This page explains stylistic choices, common mistakes, and implementation tips for writing technical documentation.

​
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: When you know which writing principles you want to implement, automate as much as you can. You can use CI checks or linters like Vale.

Content types

Choose the right content type for your documentation goals.

Accessibility

Make your documentation accessible to more users.

Format text

Learn text formatting and styling options.

SEO best practices

Improve documentation discoverability.
To find navigation and other pages in this documentation, fetch the llms.txt file at: https://mintlify.com/docs/llms.txt