Enhance your software documentation: The impact of active voice
Active voice makes software documentation clearer, concise, and more engaging. Learn how it improves user comprehension, speeds up reading, and reduces ambiguity. Discover industry best practices, when passive voice works, and tools to optimize your writing for better documentation.
- Written by
- Arun Bhalla (opens in a new tab)
- Published on
- Read time
- 5 min
Did you know that using active voice can cut down documentation length by up to 15%, making it clearer and easier to follow? Imagine reading instructions that feel direct and actionable rather than vague and confusing. Research from the Nielsen Norman Group shows that clear, concise documentation improves usability and reduces cognitive load, helping users get things done faster.
If you've ever stumbled over software documentation that felt like a puzzle, chances are it leaned too much on passive voice. Companies like Google, Mailchimp, and OpenStack emphasize active voice for a reason—it makes documentation more user-friendly and effective. Let’s dive into why active voice matters and how you can start using it to create better, clearer documentation.
The problem: ambiguity and inefficiency in technical documentation
Technical documentation exists to help users navigate software, but when it's unclear, it does the opposite. Passive voice can make instructions harder to follow, causing frustration, inefficiency, and even an increase in support tickets.
Take this sentence: “The configuration file is updated before deployment.” Who is updating it? When? Now compare that to: “Update the configuration file before deployment.” Clear, direct, and actionable.
When users struggle, they don’t just waste time—they might give up or submit a support ticket instead of solving the issue themselves. The goal? Make documentation that’s easy to read, easy to follow, and easy to act on.
Why active voice matters
Active voice ensures clarity, speeds up understanding, and makes documentation feel more engaging. Let’s break it down:
1. Clarity and directness
Active voice eliminates ambiguity by making it clear who is performing an action. For example, Google's developer documentation style guide recommends “Send a query to the service” instead of “The service is queried.”
2. Conciseness
Wordy documentation can overwhelm readers. Active voice often requires fewer words, making content more digestible. The Knowledge Owl blog notes that using active voice can reduce word count by 10-15%, which is crucial for online readers with limited attention spans. Research from the Nielsen Norman Group further supports this, showing that concise writing improves scannability and comprehension.
3. Engagement and accessibility
Active voice makes documentation more engaging. Compare:
- Passive: The Submit button should be clicked to proceed.
- Active: Click the Submit button to proceed.
Which one is easier to follow? The active version tells the user exactly what to do. Directness not only improves clarity but also enhances engagement and accessibility, making instructions more intuitive and actionable for all users.
When to use passive voice
While active voice should be the standard, passive voice has its place. Here are three key situations where it makes sense:
1. Error messages and troubleshooting
Avoid blaming users. Instead of saying, “You entered an invalid password,” a more neutral option is “An invalid password was entered.” Research from Microsoft’s UX guidelines suggests that passive voice in error messages reduces user frustration and blame perception.
2. When the actor is unknown or irrelevant
If who performed the action doesn’t matter, passive voice keeps the focus where it belongs. For example: “The database was updated.” In this case, the action is more important than who did it.
In complex or distributed systems where multiple processes interact asynchronously, passive voice can help describe actions without assigning responsibility to a single entity. For example, instead of saying, "The server updated the cache," you might say, "The cache was updated," since the update could have been triggered by multiple sources within the system.
3. Emphasizing the object over the actor
Sometimes, what happened is more important than who did it. For example: “The file is saved automatically by the application.” This keeps the focus on the file while still clarifying the actor, distinguishing it from cases where the actor is unknown or irrelevant.
Industry standards and best practices
Many top companies advocate for active voice in documentation:
- Google: The Google developer documentation style guide recommends active voice for clarity while acknowledging some exceptions for passive voice.
- Mailchimp: Mailchimp’s style guide encourages active voice to ensure accessibility for non-technical users.
- OpenStack: OpenStack’s contributor guide highlights active voice for keeping documentation clear and engaging.
Actionable solutions and best practices
Want to make your documentation better? Here’s how to get started:
- Use style guides: Follow industry standards such as the Google Developer Documentation Style Guide or Mailchimp Content Style Guide.
- Leverage AI-powered tools: Tools like Grammarly, the Hemingway App, and EkLine.io help identify and correct passive voice in real-time while enforcing a consistent writing style.
- Adopt a Docs-as-Code approach: Using linting tools like Vale ensures documentation follows predefined style rules and maintains clarity.
Practical examples: active vs. passive voice
| Context | Active voice example | Passive voice example | Preferred choice |
|---|---|---|---|
| User instruction | "Click the Submit button." | "The submit button is clicked." | Active (clearer) |
| Error message | "The system encountered an error." | "An error was encountered." | Passive (neutral) |
| Reference material | "The system updates the database." | "The database is updated by the system." | Active (direct) |
| Unknown actor | "Someone deleted the file." | "The file was deleted." | Passive (focus on action) |
Conclusion
Active voice is a game-changer for software documentation. It makes content clearer, shorter, and easier to follow—helping users accomplish tasks with minimal frustration.
If your documentation feels wordy or unclear, start by reviewing it for passive voice and revising it for clarity. Use AI-powered tools like Grammarly, Hemingway, and EkLine.io to streamline the process. Train your team on best practices, test readability, and continuously refine your documentation.
The next time you write documentation, think about your reader. Make it clear. Make it direct. And most importantly, make it easy for them to succeed.
Key references
- Nielsen Norman Group: How Users Read on the Web
- Microsoft UX Guidelines: Writing Error Messages
- Journal of Business and Technical Communication: Study on Active vs. Passive Voice
- Google Developer Documentation Style Guide - Active Voice
