5 exercises — when to use passive voice in API docs, incident reports, release notes, and specifications.
0 / 5 completed
1 / 5
Which sentence is most appropriate for API documentation?
Technical documentation typically uses passive voice when the actor is the system, is obvious, or is irrelevant to the reader. "All requests are authenticated" keeps the focus on what happens to the subject. Options A and D assign agency to a specific actor, which is less appropriate in formal API docs.
2 / 5
Rewrite in passive voice: "The server sends an email confirmation after registration." → "An email confirmation _____ after registration."
The present simple passive is is/are + past participle: is sent. This construction is extremely common in technical documentation, system descriptions, and API references: "Requests are rate-limited.""Errors are returned as JSON.""The token is refreshed automatically."
3 / 5
When is passive voice most appropriate in technical writing?
Use passive voice when: (1) the actor is obvious or irrelevant ("Data is encrypted at rest"); (2) you're describing what a system does ("Requests are rate-limited to 100/minute"); (3) you want to keep incident reports blameless ("The service was misconfigured" rather than "Alice misconfigured the service"). Avoid passive in conversational messages where active voice is clearer.
4 / 5
Choose the most appropriate passive sentence for an incident report:
Incident reports should be blameless — they focus on what happened and its impact, not on who caused it. Passive voice achieves this naturally. Option A assigns personal blame; option C is vague and informal; option D uses "got" which is informal. Good incident writing is factual, specific, and non-accusatory: "The configuration was changed. The service went down. The alert was triggered at 14:23."
5 / 5
Complete the release note: "All deprecated endpoints _____ (remove) in version 3.0. Affected clients _____ (encourage) to migrate before November 30."
Release notes use the future passive (will be + past participle) for announced changes: "will be removed", "will be deprecated", "will be required". For current-state recommendations, are + past participle: "are encouraged", "are advised". These passive constructions appear in migration guides, changelogs, and deprecation notices across all major platforms.