5 exercises — choosing between active and passive voice in commit messages, RCA documents, API docs, and user stories.
0 / 5 completed
1 / 5
In a Git commit message, which phrasing follows best practices?
Git commit messages use the imperative mood in active voice — write as if giving an instruction: "Refactor", "Fix", "Add", "Remove". This is the convention established by Git itself and recommended in most style guides (including the Linux kernel guide). The subject ("you" = the commit) is implied. Passive voice in commit messages ("was refactored") is harder to scan in git log and buries the action. Never include the engineer's name in a commit message body — that is already in the author field.
2 / 5
An RCA (root cause analysis) document states the finding. Which sentence is most appropriate?
In RCA documents, passive voice is preferred when reporting system failures and incidents. The focus should be on what happened to the system, not on assigning individual blame. "The production database was deleted" centres the impact without naming a person — this is standard blameless post-mortem practice. Naming an individual (option A) creates blame culture and is discouraged in incident retrospectives. "Got deleted" is too informal for a professional document. Passive voice here is a deliberate, humane technical writing choice.
3 / 5
In API reference documentation, which sentence better explains what an endpoint does?
Modern API documentation prefers active voice with "we" because it is clearer, shorter, and more direct. "We process your request" clearly states the actor (our system = we) and the action. Option A ("Our system will process") is slightly wordier. Option B (passive) is correct but less direct — the passive buries the action after "is processed". Option D ("get processed") is informal and non-standard in professional API docs. Style guides from Stripe, Twilio, and Google APIs all recommend active voice as the default for endpoint descriptions.
4 / 5
A user story reads: "As a user, I want to _____ so that I can access my dashboard." Which verb form correctly completes an active-voice user story?
User stories follow the standard format: As a [user], I want to [action], so that [benefit]. The "I want to" frame requires an active infinitive — a bare infinitive in active voice that expresses what the user does, not what happens to them. "Log in" is correct: the user performs the action. "Be logged in" (passive infinitive) shifts agency away from the user and is grammatically awkward after "I want to". Good user stories keep the user as the active agent, which also helps developers understand the required UX flow.
5 / 5
A system architecture document describes data flow. Which sentence is most appropriate for describing an automated system process where the human actor is unknown or irrelevant?
Passive voice is appropriate in technical architecture documentation when the actor is a system component, unknown, or irrelevant to the reader. "The event is sent to the message queue" keeps the focus on the data flow — what happens to the event — which is what the reader needs to understand the architecture. "Someone sends" is incorrect because an event is triggered by a system, not a person. "We send" implies human action. The present simple passive ("is sent") is the standard choice in architecture diagrams and sequence descriptions.