This page explains stylistic choices, common mistakes, and implementation tips for writing technical documentation.
Writing principles
- Be concise: Users read documentation to achieve goals. Get to the point quickly.
- Prioritize clarity: Use simple, direct language. Avoid jargon and complex sentences.
- Use active voice: Write “Create a configuration file” instead of “A configuration file should be created.”
- Make content skimmable: Use clear headings, short paragraphs, and bullet points for easy scanning.
- Write in second person: Address readers as “you” to make instructions easier to follow and more personal.
Common mistakes to avoid
- Spelling and grammar errors: Even minor mistakes reduce credibility and readability.
- Inconsistent terminology: Switching between “API key” and “API token” confuses users. Use consistent terms throughout.
- Product-centric language: Users lack internal context. Use familiar language that aligns with how they think.
- Colloquialisms: Avoid informal expressions, especially in documentation intended for localization. They reduce 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
