How to Use Active Voice in Technical Documentation
Why active voice makes technical documentation clearer, faster to read, and easier to act on — with real IT examples and before-and-after rewrites.
One of the most common mistakes in technical documentation is overusing passive voice. Sentences like “the configuration file should be updated” or “the error was thrown by the service” leave readers asking: who does what? Active voice removes that ambiguity and makes your docs faster to read and easier to follow.
This guide explains the difference, shows you why it matters in IT contexts, and gives you practical rewrite examples.
What Is Active Voice?
In active voice, the subject of the sentence performs the action:
“The server processes the request.”
In passive voice, the subject receives the action — often hiding who or what is responsible:
“The request is processed by the server.”
Both sentences mean the same thing, but the active version is shorter and clearer.
Why Passive Voice Creeps Into Technical Writing
Engineers often write passively for two reasons: it feels more formal, and it avoids blaming a specific component or team. But documentation is not about formality — it is about clarity. Readers need to know who acts and what they should do.
Why Active Voice Matters in IT Documentation
1. Instructions Are Clearer
When writing procedures and tutorials, passive voice creates confusion about who must act:
| Passive (unclear) | Active (clear) |
|---|---|
| “The database must be backed up before migration." | "Back up the database before you run the migration." |
| "The token should be stored in an environment variable." | "Store the token in an environment variable." |
| "An error will be returned if the field is empty." | "The API returns an error if the field is empty.” |
2. Errors Are Easier to Diagnose
In incident reports and runbooks, passive voice hides the source of a failure:
Passive: “The service was restarted and the memory leak was resolved.”
Active: “The on-call engineer restarted the service. The memory leak resolved after the restart.”
The active version tells you who restarted the service — critical for post-mortems.
3. API Documentation Reads Faster
Developers scanning API docs want to know what they do and what the API does:
Passive: “A 200 response is returned when authentication is successful.”
Active: “The API returns a 200 response when authentication succeeds.”
Before and After: Real IT Examples
README Instructions
Before (passive):
“Dependencies should be installed before the application is started. The config file should be copied from the example template and environment variables should be set.”
After (active):
“Install the dependencies before you start the application. Copy the config file from the example template and set your environment variables.”
Error Messages
Before (passive):
“The request could not be processed because the required fields were not provided.”
After (active):
“The API could not process the request because you did not provide the required fields.”
Architecture Documents
Before (passive):
“Messages are published to the queue by the producer service. They are then consumed by the worker.”
After (active):
“The producer service publishes messages to the queue. The worker then consumes them.”
When Passive Voice Is Acceptable
Active voice is not always the right choice. Passive voice works well when:
- The actor is unknown or irrelevant: “The log file is generated at midnight.”
- You want to emphasise the object, not the actor: “The API key is exposed in the logs” (the key matters more than who exposed it)
- Writing scientific or formal reports where convention expects it
The rule of thumb: if readers need to know who does something in order to act on the information, use active voice.
Practical Phrases for Active Technical Writing
Use these patterns when rewriting your docs:
- “The system returns…” instead of “A response is returned…”
- “Run the following command…” instead of “The following command should be run…”
- “The developer configures…” instead of “The configuration is done by…”
- “Call the endpoint with…” instead of “The endpoint should be called with…”
Switching to active voice is one of the highest-return improvements you can make to your documentation. It takes practice, but the habit becomes natural quickly. Start by reviewing your README files — they are usually the most passive-heavy documents in any project.
Communicating Clearly with Non-Native Colleagues
As technical writers, we often strive for clarity and precision in our documentation. However, when collaborating with developers who are still building their command of English – particularly nuanced aspects of professional phrasing – it’s crucial to adjust our approach. Simply using active voice isn’t enough; we need to consider how that voice impacts those whose first language isn’t English. The goal shifts from just conveying information to ensuring understanding.
One common area of confusion stems from the passive voice, frequently used to obscure responsibility or when the actor is unknown. While perfectly acceptable in some contexts (e.g., “The server was updated”), relying heavily on it can overwhelm non-native speakers who may struggle with sentence structure and identifying the agent performing an action. For example, instead of “A bug was reported,” a clearer, more direct statement – “John reported a bug” – immediately conveys accountability and provides context. Similarly, rewording instructions like “The file should be uploaded” to “Please upload the file” is often easier for those learning English because it explicitly names the action required.
Furthermore, we need to be mindful of idioms and colloquialisms. Even seemingly straightforward phrases can carry hidden meanings that are difficult for non-native speakers to decipher. Instead of saying “Let’s circle back on this,” which relies heavily on figurative language, a more explicit instruction like “Let’s revisit this topic” removes ambiguity. When reviewing code comments, actively seeking out opportunities to replace passive constructions with active ones, alongside simplified phrasing, can make a significant difference. For instance, instead of “The database was queried,” we could write: “David queried the database.” This simple change immediately clarifies who performed the action and makes the sentence more accessible.
Finally, during code review comments, focusing on clear, concise instructions is paramount. A comment like “Fix this issue” is vague. A better approach would be: “Please update the authentication module to resolve the login error.” Providing specific steps – even if they seem obvious to a native speaker – dramatically improves comprehension and reduces the potential for misunderstandings. Remember, our role isn’t just to document code; it’s to bridge communication gaps and ensure everyone on the team is working with the same understanding.