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.
Navigating Nuance: Passive Voice & Developer Communication
The pervasive nature of technical documentation often leads to a reliance on the active voice – a natural inclination for clear communication. However, understanding when and how to employ the passive voice can significantly improve clarity, reduce ambiguity, and enhance the professionalism of your writing, particularly when documenting complex systems or incident reports where precise wording is paramount. For non-native English speakers in particular, mastering subtle nuances like this can greatly strengthen comprehension across cultures. The key isn’t avoiding the passive entirely – it’s using it strategically.
One common scenario arises in describing system behavior. Instead of stating “The server responded with an error,” a passive construction – “An error was returned by the server” – shifts the focus from the action itself to the outcome. This is particularly useful when the who or how is less important than the fact that an error occurred, which is vital in incident reports where quickly establishing what happened is more crucial than assigning blame. Similarly, in API documentation, stating “The endpoint returns a 404 status code” can be strengthened to “A 404 status code is returned by the endpoint,” emphasizing the response rather than the process of requesting it. This avoids potentially confusing details about the request itself and focuses on the documented result. Furthermore, in situations where the actor performing an action is unknown or irrelevant (e.g., “The system was updated”), passive voice provides a neutral and objective tone.
However, over-reliance on the passive can lead to convoluted sentences and reduced clarity. It’s crucial to balance it with active voice for directness and engagement. Consider this Slack message: “We need to investigate why the database is down.” – Active! Now compare it to “It was determined that the database was down,” which, while technically correct in a formal report, feels clunky and less immediate. The goal is not to only use passive voice; it’s to recognize its power when appropriate for precise description and objective reporting.
Here’s an example of using curl to retrieve data – demonstrating how the passive might be relevant in documenting API interactions:
curl -s -o /dev/null -w "%{http_code}" https://api.example.com/users/123In this command, curl performs the action of requesting data. Documenting this process might benefit from describing what’s happening – “The API endpoint is queried…” or “Data is retrieved…”.
Ultimately, mastering the passive voice in technical documentation isn’t about rigid adherence to a rule; it’s about understanding its strategic value and using it judiciously to communicate effectively.