"Avoid passive voice" is the most repeated - and most misunderstood - rule in technical writing. Then you open Stripe's docs and find "The payment is refunded automatically", passive and perfect. So which is it?
Why the Rule Exists
Passive hides the actor: "The file was deleted" - by whom? A script? A user? A bug? In troubleshooting docs, that ambiguity costs real time. Active voice is also shorter and easier to scan.
When Passive Is Actually Right
- The actor is irrelevant: "Requests are rate-limited per API key."
- The receiver is the topic: "The token is returned in the response body."
- System behavior, not user action: "Logs are rotated every 24 hours."
- Blame doesn't help: "The config file was corrupted" (vs. "You corrupted the config file")
The 3-Step Rewrite Pass
-
Fix passives that hide an actor the reader needs - the only mandatory category: "An error occurred" → "The SDK retries failed requests 3 times, then raises
TimeoutError" - Run a readability check to find where passive density and sentence length pile up
- Keep system-behavior passives - "Responses are cached for 60 seconds" is correct and shorter than its active twin
Most tools flag every passive equally, which is why engineers disable them. Lint surfaces style issues as low-severity hints instead of red errors: real errors first, style judgment second, code tokens never touched.
Passive voice is a tool, not a sin. Kill it when it hides an actor; keep it when the system is the subject.
👉 Try Lint free - 3 checks/day, no signup. BYOK: unlimited, $0.
Top comments (0)