Grammar: Using Passive Voice Correctly in Technical Documentation

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.

Navigating Nuance: Passive Voice for Non-Native Speakers

The concept of passive voice can be particularly tricky for developers learning professional English. Often, it’s perceived as overly formal or even evasive, a remnant of academic writing that doesn’t translate well to the direct, actionable style needed in software development. However, understanding its strategic use – and recognizing when active voice is demonstrably stronger – is crucial for clear technical communication. The core issue isn’t the passive voice itself; it’s often about why it’s being used. Frequently, non-native speakers lean towards passive constructions simply because they mirror sentence structures more common in their first language, leading to a perceived need for complexity where simplicity prevails.

Let’s consider a common scenario: receiving feedback on a pull request. Imagine you’ve submitted a PR containing significant refactoring of the logging system. A reviewer might leave this comment in the issue tracker: “The error handling was updated.” While grammatically correct, it lacks specific information. It doesn’t tell you what needs to be changed, or why. A more effective response, employing active voice, would be: “The reviewer has identified a potential race condition within the error handling logic. Please ensure all asynchronous operations are properly synchronized before merging.” This revised phrasing clearly directs your attention to the problem and explains its significance. The passive construction obscures responsibility – who ‘was updated’ isn’t important; what needs to happen is.

Furthermore, when crafting PR descriptions, the focus should be on the actions you took, not just the changes that occurred. Instead of stating “The API endpoint was modified,” write: “I implemented a new authentication layer for the /users endpoint using OAuth 2.0, as detailed in the updated design document.” This active phrasing highlights your contribution and provides context for the change. It also allows reviewers to quickly assess whether the implementation aligns with documented requirements. Avoiding overly complex sentence structures is key; clarity should always trump stylistic flourishes.

Finally, remember that technical documentation – API specifications, user guides, and internal reports – benefits immensely from precise language. Ambiguity can lead to misinterpretations and costly errors. While passive voice might occasionally be appropriate when describing a process without assigning responsibility (e.g., “The data was validated against the schema”), prioritize active constructions whenever possible for greater clarity and accountability.

# Example: Using `pytest` to verify a function's output - demonstrates clear action
pytest tests/my_module.py --verbose