Using Passive Voice in Technical Documentation
When to use passive voice in API docs, changelogs, and postmortems — and when to avoid it. Practical examples and grammar guidance for technical writers.
The passive voice has a poor reputation in writing guides. “Avoid passive voice,” style guides often say. But in technical documentation, the passive voice is not a mistake — it is a tool. Used correctly, it improves clarity and suits the context. Used incorrectly, it obscures responsibility and confuses readers. This guide explains when passive voice serves you well and when to reach for the active voice instead.
What Is the Passive Voice?
In the active voice, the subject performs the action:
“The API returns a 404 error when the resource is not found.”
In the passive voice, the subject receives the action, and the actor is either moved to a “by” phrase or omitted entirely:
“A 404 error is returned when the resource is not found.”
Both sentences are grammatically correct. Whether one is better depends on context.
When Passive Voice Is Appropriate
1. API Documentation — When the Actor Is Obvious or Irrelevant
In API documentation, you are describing what the system does, not who does it. The actor (the API, the system, the server) is understood. Passive voice keeps the focus on what happens.
“The request is validated against the JSON schema before processing.” “A confirmation email is sent to the registered address after sign-up.” “Access tokens are invalidated after 24 hours or on explicit logout.”
These are clear, concise, and correctly focused on the system’s behaviour rather than on naming an obvious actor.
2. Changelogs — Describing Changes Without Implying Individual Blame or Credit
Changelogs document what changed, not who changed it. Passive voice suits this naturally.
“The rate limit headers have been updated to use the
RateLimit-Policyformat.” “Support for TLS 1.0 and 1.1 has been removed.” “The default timeout has been increased from 30 to 60 seconds.”
These sentences follow the standard changelog conventions used by projects like Stripe, GitHub, and npm.
3. Postmortems — Removing Blame from Individuals
Blameless postmortem culture discourages naming individuals responsible for mistakes. Passive voice supports this:
“The deployment was triggered at 14:32 UTC without the required change approval.” “The alert was dismissed, as it had been triggered falsely several times during the previous week.”
These formulations acknowledge what happened without publicly attributing blame to a specific person.
4. Security Disclosures — Formal, Impersonal Tone
Security advisories often use passive voice to maintain a formal register and describe impact clearly:
“This vulnerability allows an authenticated user to access data belonging to other users.” “Affected versions are 3.1.0 through 3.4.2. The vulnerability was introduced in commit a3f92c.”
When to Avoid Passive Voice
1. Instructions and Tutorials — Use Active Voice for Clarity
When you are telling a user what to do, passive voice creates ambiguity. Who does the action — the user, the system, or both?
Passive (unclear):
“The configuration file should be updated with the API key.”
Active (clear):
“Update the configuration file with your API key.”
Always use the imperative (active) voice in step-by-step instructions.
2. When the Actor Matters — Name Them
If who did something is relevant and known, passive voice hides important information:
Passive (misleading):
“The database was deleted.”
Active (precise):
“The cleanup script deleted the staging database.”
3. When Passive Creates Ambiguity
“The error was caused by a missing field.” — caused by whom? In the request, the response, or the configuration?
When the passive voice creates questions that active voice would answer, switch:
“The missing
userIdfield in the request body caused the error.”
Quick Reference
| Situation | Recommended Voice | Example |
|---|---|---|
| API behaviour description | Passive | ”A token is returned on success.” |
| Step-by-step instruction | Active | ”Click Save to continue.” |
| Changelog entry | Passive | ”The endpoint has been deprecated.” |
| Postmortem factual account | Passive | ”The alert was silenced at 02:10.” |
| Assigning responsibility | Active | ”The deployment script removed the wrong table.” |
| Tutorial or guide | Active | ”Import the library at the top of your file.” |
Practical Phrases Using Passive Voice Correctly
- “The authentication token is included in the
Authorizationheader.” - “Deprecated endpoints will be removed in version 4.0.”
- “The incident was detected at 09:15 UTC and resolved by 10:40 UTC.”
- “Rate limits are enforced per API key, not per IP address.”
- “Breaking changes are announced at least 90 days before removal.”
The passive voice is a legitimate grammatical tool with a proper place in technical communication. The goal is not to eliminate it — it is to use it intentionally. When the actor is irrelevant, unknown, or better left unnamed, passive voice serves you well. When the actor matters, or you are giving instructions, active voice is clearer. Knowing the difference is what separates competent technical writers from excellent ones.
Navigating Nuances: Passive Voice for Global Teams
The core principle of using passive voice – conveying action rather than the actor – remains vital, especially when considering teams distributed across different linguistic backgrounds. The issue isn’t simply about grammatical correctness; it’s about clarity and reducing potential ambiguity. For non-native English speakers, particularly those whose first language relies heavily on subject-verb agreement and direct attribution, passive constructions can often feel more natural and easier to parse than active sentences. However, overreliance creates a stylistic hurdle – a tendency to default to “The database was updated” when “We updated the database” would be equally clear and potentially more engaging.
In a global tech environment, where communication styles vary widely, a key challenge is translating not just words but also intent. A direct, active sentence can sometimes feel accusatory or overly assertive, especially if the context involves a bug fix or an incident report. Passive voice softens this potential friction by focusing on the outcome – “The error was resolved” – rather than placing blame or highlighting individual responsibility (which might be culturally sensitive). This is particularly important when documenting complex processes for teams where technical expertise isn’t uniformly distributed. We need to prioritize understanding over precise attribution.
Consider a Slack message during a critical bug triage: “The service degraded.” While technically accurate, it’s terse and lacks context. A more approachable phrasing – “Service degradation was detected” – allows the team to quickly understand the problem without needing to immediately investigate who caused it or why. Similarly, in a pull request description for a documentation update, stating “The API endpoint was modified” is preferable to “You modified the API endpoint” which could be perceived as critical feedback. The goal is always to facilitate collaboration and knowledge sharing, not to create potential points of misunderstanding based on linguistic differences.
Let’s illustrate with an example related to monitoring alerts:
# Example CLI command for checking system health (using a hypothetical tool)
system_health check --instance 'production-server-01' | jq '.status'This simple command, used in a postmortem documenting a performance issue, highlights the importance of focusing on the result – “The system health check returned an error” – rather than dwelling on the specific action taken (which might be obscured by technical jargon or different interpretations). Ultimately, effective documentation for diverse teams hinges on choosing phrasing that is both precise and universally understandable, acknowledging that clarity often outweighs stylistic preference.