Grammar: Passive Voice in Technical Documentation
When and how to use the passive voice in technical writing — with examples from real documentation, API references, and incident reports.
The passive voice has a bad reputation in general writing advice — “avoid the passive voice” is one of the most common tips in English style guides. But in technical writing, the passive voice is not only acceptable; it is often the correct choice. Understanding when to use it (and when not to) will make your documentation significantly clearer.
Active vs. Passive: A Quick Review
Active voice: The subject performs the action.
“The system sends a confirmation email.”
Passive voice: The subject receives the action. The agent (who does the action) is either moved to the end with “by” or omitted entirely.
“A confirmation email is sent by the system."
"A confirmation email is sent.”
The passive is formed with to be + past participle:
| Tense | Example |
|---|---|
| Present simple | ”The request is validated.” |
| Past simple | ”The request was rejected.” |
| Future | ”The data will be encrypted.” |
| Present perfect | ”The token has been revoked.” |
| Modal | ”Errors must be logged.” |
When to Use the Passive in Technical Writing
1. When the actor is unknown or unimportant
In documentation, the reader often does not need to know who performs an action — just what happens:
“The password is hashed using bcrypt before storage.” — We don’t need to say “the system hashes…”
“Requests are rate-limited to 100 per minute.”
“The token is included in the Authorization header.”
2. When focusing on the object, not the subject
In API documentation, the focus is on what happens to data, not on who does it:
“The response body is returned as JSON.”
“Errors are represented as problem detail objects (RFC 7807).”
“Pagination is controlled via the
pageandlimitquery parameters.”
3. In blameless incident reports
The passive removes individuals from the narrative, which is appropriate in post-mortems:
“The production database was accidentally truncated during the migration.” (not: “John accidentally truncated…”)
“Monitoring alerts were not configured for the new service.”
“The rollback was initiated after five minutes of elevated error rates.”
4. In warnings and requirements
Passive constructions with modals are standard in technical specifications:
“All requests must be authenticated.”
“Sensitive data should be encrypted at rest.”
“Error responses must not include stack traces in production.”
When NOT to Use the Passive
1. When the actor matters
If the reader needs to know who does something, use the active voice:
“Admins can revoke tokens from the dashboard.” (not: “Tokens can be revoked…”)
“The deployment script backs up the database before running migrations.”
2. In step-by-step instructions
Instructions should use the imperative or active voice — it is clearer and more direct:
“Run
npm installto install dependencies.” (not: “Dependencies should be installed by running…”)
“Click Save to apply your changes.” (not: “The Save button should be clicked…“)
3. When it creates ambiguity
The passive can hide who is responsible:
“The issue was not raised in time.” — Who should have raised it?
“The requirements were misunderstood.” — By whom?
If the actor matters for understanding the text, include it.
Common Passive Patterns in Technical Documentation
| Pattern | Example |
|---|---|
| ”X is used to Y" | "JWT is used to authenticate API requests." |
| "X is returned when Y" | "A 404 is returned when the resource is not found." |
| "X must be Y" | "The field must be provided in ISO 8601 format." |
| "X is stored as Y" | "Timestamps are stored as Unix epoch integers." |
| "X can be configured via Y" | "Logging can be configured via the LOG_LEVEL environment variable." |
| "X was introduced in Y" | "This endpoint was introduced in API version 2.3." |
| "X has been deprecated" | "This parameter has been deprecated. Use userId instead.” |
Quick Reference: Active or Passive?
Ask yourself:
- Does the reader need to know who does this? → Active
- Is this a step-by-step instruction? → Active (imperative)
- Is the focus on what happens to data or a system? → Passive
- Is the actor unknown, irrelevant, or inappropriate to name? → Passive
- Is this a requirement or constraint? → Passive with modal (“must be”, “should be”)
The passive voice in technical writing is a tool, not a mistake. Used with intention, it makes documentation cleaner, more objective, and focused on what the reader actually needs to know: what the system does, not who does it.