Grammar: Using Passive Voice Correctly in Technical Documentation
Learn when and how to use passive voice in technical specs, reports, and API docs — and when active voice is the better choice for clarity.
Passive voice is one of the most debated features of technical English. Some style guides ban it; others embrace it. The truth is more nuanced: passive voice is a powerful tool when used for the right reasons, and a clarity killer when used by habit.
What Is Passive Voice?
In active voice, the subject performs the action:
“The deploy script updates the database.”
In passive voice, the subject receives the action:
“The database is updated by the deploy script.”
The passive is formed with a form of “to be” + the past participle of the verb.
When to Use Passive Voice in Technical Writing
1. When the actor is unknown or irrelevant
If what happened matters more than who did it, passive is the natural choice.
- “The error was logged at 14:32 UTC.” (We do not know which service logged it — or it does not matter.)
- “All requests are validated before reaching the service layer.” (The actor — the middleware — is implicit and obvious.)
- “The configuration was changed three days before the incident.”
2. When describing system behaviour
Passive voice describes what a system does to data very naturally:
- “The request is routed to the nearest healthy instance.”
- “Tokens are rotated every 24 hours.”
- “Sensitive fields are encrypted at rest using AES-256.”
- “The payload is compressed before transmission.”
3. In methodology and procedure sections
When describing a process that applies universally (not tied to one person), passive is conventional:
- “The migration script is run on all nodes sequentially.”
- “Pull requests must be reviewed by at least two engineers.”
- “Logs are retained for 90 days before automatic deletion.”
4. In scientific and formal reports
Technical specifications and audit reports conventionally use passive voice for objectivity:
- “The system was tested against 10,000 concurrent users.”
- “Results were recorded at five-minute intervals.”
- “The latency was measured at the gateway level.”
When NOT to Use Passive Voice
1. When the actor matters
If responsibility or ownership is important, use active voice:
- Passive (evasive): “The database was deleted.”
- Active (clear): “The automated cleanup job deleted the production database.”
2. When you want strong, direct instructions
Documentation and runbooks read more clearly in active voice:
- Passive (weak): “The service should be restarted by the on-call engineer.”
- Active (clear): “Restart the service using
systemctl restart payment-api.”
3. When it creates ambiguity about timing
- Passive (unclear): “The migration is completed.”
- Active (clear): “The migration completes before the service starts.”
The “By” Test
If you can add “by someone/something” after the passive verb and it sounds natural, the passive may be appropriate. If the “by” phrase sounds strange or obvious, consider rewriting in active voice.
- “Errors are caught by the global error handler.” ✓ (The actor adds useful information.)
- “The button is clicked by the user.” ✗ (Obviously the user — rewrite: “The user clicks the button.”)
Mixing Passive and Active in the Same Document
Good technical writing mixes both voices deliberately:
“The service receives a request (active) and the request is validated against the schema (passive). If validation fails, the service returns a 400 error (active). All validation errors are logged for audit purposes (passive).”
This mixture is natural and readable. The key is intentionality — not avoiding one voice or the other, but choosing the one that best serves clarity.
Common Passive Constructions in Technical Docs
| Context | Example |
|---|---|
| API docs | ”The response body is returned as JSON.” |
| Security docs | ”Passwords are hashed using bcrypt with a cost factor of 12.” |
| Runbooks | ”If the primary is unreachable, traffic is redirected automatically.” |
| Release notes | ”A race condition has been fixed in the payment flow.” |
| Architecture docs | ”Services are deployed independently using container images.” |
Passive Voice Grammar Quick Reference
| Tense | Active | Passive |
|---|---|---|
| Present simple | ”The system sends logs." | "Logs are sent.” |
| Present continuous | ”The system is sending logs." | "Logs are being sent.” |
| Past simple | ”The system sent logs." | "Logs were sent.” |
| Present perfect | ”The system has sent logs." | "Logs have been sent.” |
| Modal (must) | “You must restart." | "The service must be restarted.” |
| Modal (will) | “The job will run." | "The job will be run.” |
Key Takeaways
- Use passive voice when the actor is unknown, irrelevant, or when describing system behaviour.
- Use active voice for instructions, runbooks, and when ownership matters.
- The “by” test: if the “by [actor]” phrase is useful, passive is appropriate; if it is obvious, use active.
- Good technical writing mixes both voices — the goal is clarity, not ideological consistency.
- Modal passives (“must be restarted,” “should be reviewed”) are common and appropriate in procedures and policies.