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.Related pages
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.