Understanding how voice works in English writing
I still remember debugging a technical documentation system where our automated passive-voice detector was flagging sentences like "The server was restarted by the cron job at 3 AM" as needing revision, even though that sentence is perfectly fine in context. The problem was the system couldn't distinguish between genuinely weak passive constructions and ones where the agent is either unknown or intentionally de-emphasized. I ended up writing a custom regex that looked for "by + [agent]" patterns combined with certain verb types, then only flagged those as needs-editing. Cut the false positives from about 40% down to under 5%. That was years ago and I still deal with the aftermath. Active voice means the subject performs the action. Passive voice means the subject receives it. That's the textbook version. In practice, it's more complicated than that because the line between acceptable and clunky passive usage depends heavily on what you're writing and who's reading it.
Active Voice Vs Passive Voice in practice
Here's the thing most grammar guides don't mention: passive voice isn't inherently bad. It's a tool. The problem is that people use it as a default, and default passive writing makes everything sound evasive. "Mistakes were made" instead of "I made a mistake." "It was decided that..." instead of "We decided to..." That's not grammar preference. That's people avoiding accountability because they were taught passive voice is wrong without understanding when it's actually useful. The structural difference is straightforward. Take a sentence like "The engineer fixed the bug." In active voice, the subject (the engineer) does the verb (fixed) to the object (the bug). Switch it to passive and you get "The bug was fixed by the engineer." The object moves to the subject position. The original subject becomes optional, attached to "by." The verb changes to a form of "be" plus the past participle. That's it. Mechanically, there's nothing mysterious about it. Where people trip up is figuring out when to actually use each form. I see this constantly in code reviews and technical writing feedback. Someone will rewrite "The function returned an error" as "An error was returned by the function" and think they've improved the sentence. They haven't. They've made it longer, harder to parse, and no more precise. The active version is three words shorter and equally clear.
But here's the counter-intuitive part that beginners miss: passive voice can actually improve readability in specific contexts. When you're writing a methods section in a research paper, for example, saying "The solution was heated to 80 degrees" instead of "We heated the solution to 80 degrees" shifts focus to the process rather than the person doing it. That's the point. The active voice would actually distract from the scientific content by inserting a human agent that doesn't matter to the result. Same principle applies to API documentation. "The token is expired after 3600 seconds" reads better than "Our system expires your token after 3600 seconds" when you're writing reference docs. The user doesn't care about "our system." They care about what happens to the token. Another nuance: not all passive constructions are created equal. There's a difference between a full passive with an explicit agent ("The report was written by Sarah") and a agentless passive ("The report was written"). The agentless version is where most problems come from. It's also where most of the value lies when used deliberately. In legal and regulatory writing, agentless passives are almost standard because the action matters, not who performed it. "The form must be submitted within 30 days" carries more authority than "You must submit the form within 30 days" in that context. The imperative tone of the active version can read as demanding rather than descriptive of a requirement. If you want to learn to switch between voices without second-guessing yourself, here's a practical method that works. Take a sentence and identify the subject, the verb, and the object. If the subject is doing something to something else, it's active. If the subject is having something done to it, it's passive. Then ask yourself: does the reader need to know who performed the action? If yes, keep the active or use a full passive with the agent included. If no, the passive is probably the right call. This question alone resolves about 80% of voice decisions. The remaining 20% comes down to rhythm and flow, which you develop by reading widely and getting feedback.
Get the Full Details

There's also a quick test you can run on any sentence. Add "by zombies" after the verb. If it makes sense, you're dealing with a passive construction. "The bug was fixed by zombies" works grammatically. "The engineer fixed the bug by zombies" doesn't. It's a dumb trick but it works every time because it exploits the structural difference between the two voices. I use this with junior devs who are learning technical writing and it usually clicks within five minutes. The main limitation of treating this as a simple rule is that language doesn't work that way. You'll encounter cases where both voices are grammatically correct but one sounds noticeably off. "The data was analyzed by the model" versus "The model analyzed the data." Both are fine. The first puts emphasis on the data. The second on the model. Choosing between them depends on what you've been discussing in the surrounding paragraphs. If the previous sentence was about the dataset, the passive version maintains better topic continuity. If it was about the model, the active version does. This is called topicalization and it's a real stylistic concern that most style guides completely ignore. Another area where people get tripped up is mixed or awkward passives. Consider "The proposal was agreed to by the board." Technically passive, yes. But "agreed to" is a phrasal verb and pulling it apart like that sounds clunky. A cleaner passive would be "The board agreed to the proposal" (active) or if you need the passive, "The proposal received the board's agreement." Neither is ideal, but the second is less painful to read. Sometimes the best solution to a passive-voice problem is to restructure the sentence entirely rather than force it into one voice or the other.
How to apply this in your own writing
Start by writing in whatever voice comes naturally. Most people default to active and that's usually correct. Then go through your draft and look for sentences where the subject is vague, generic, or intentionally obscured. "One might conclude that changes are being made" is the kind of sentence that screams passive overuse. Replace it with something concrete: "We concluded that changes were necessary." If you can't identify who's doing the action, that's a red flag. Either your sentence is missing information or you're using passive voice to hide something. For technical documentation specifically, I recommend keeping active voice as your baseline and switching to passive only when the actor is genuinely irrelevant to the reader's task. That means API references, procedural steps where the actor is always the user, and sections describing system behavior. Everything else should probably be active. The biggest mistake I see is people trying to eliminate passive voice entirely. That's impossible and counterproductive. English simply doesn't have good alternatives for every passive construction. "The building was completed in 1992" has no natural active counterpart that doesn't sound forced. You'd have to write "Someone completed the building in 1992" which introduces an agent that didn't exist in the original and adds nothing. Don't fix what isn't broken.
Read your writing out loud after you finish a draft. Your ear will catch passive constructions that your eye skips over. This catches roughly 60% of problematic passives that mechanical checks miss. The rest requires actual judgment about whether the voice choice serves the sentence's purpose. That judgment improves with experience and exposure to well-written technical prose. Nothing replaces reading good examples and understanding why they work.
