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.