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.
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.
Active voice ensures clarity, speeds up understanding, and makes documentation feel more engaging. Let’s break it down:
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.”
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.
Active voice makes documentation more engaging. Compare:
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.
While active voice should be the standard, passive voice has its place. Here are three key situations where it makes sense:
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.
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.
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.
Many top companies advocate for active voice in documentation:
Want to make your documentation better? Here’s how to get started:
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.
