Style & Tone

​

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 & grammar mistakes. “Grammatical errors may seem small, but they’re a key indicator of quality. They can degrade trust in your product as well.” —Brody Klapko, Technical Writer at Stash
• 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 “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
• Splunk Style Guide
• Google Developer Documentation Style Guide

When you know which writing principles you want to implement, automate as much as you can. You can use linters (such as Vale) or your documentation provider, such as Mintlify’s CI checks.