Style and tone

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.

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 users are familiar with.
Colloquialisms. Especially for localization, colloquialisms hurt clarity.

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.