Reading time: 6 minutes
There’s a tool that we use for our Third Law blog called Yoast SEO that analyzes content for search-engine optimization as well as writing style. It often says my writing is difficult to read, which I outright ignore because I don’t think our material is intended to target your average eighth grader. However, it invariably also says that my writing uses too much passive voice. There isn’t a single blog I’ve written where it says I’m below the recommended 10% threshold of passive voice content.
It’s not just Yoast that notices. When we’re writing technical content, Nancy occasionally tries to strike my passive voice knuckles with her active voice ruler. A similarly excellent editor and copywriter Paul Leroux has writing skills that made his pieces on the QNX Auto Blog really shine. When he edited my work in the past, Paul would often point out too much passive voice usage in my drafts. In both cases, I could only push back with a nebulous complaint: “it sounds weird when you rewrite it the other way.”
Passive voice use is quite common in engineering circles. And if you’re a writer, editor, or marketer who works with engineers, no doubt you’ll agree.
What is passive voice?
Stepping back a minute, what is passive voice, and why are proper grammarians always trying to remove it from our discourse? Although there is a tool that can tell you, it’s easier to show through a couple examples:
ACTIVE: She kicked the ball.
PASSIVE: The ball was kicked by her.
ACTIVE: I am writing a new blog.
PASSIVE: The new blog is being written by me.
While active voice emphasizes the subject, passive voice deemphasizes the subject and focuses on the object. In typical dialog, passive voice leads to less clarity and ends up being a bit more convoluted – understandably a good thing to avoid under normal circumstances.
Why engineering loves the passive voice
If active voice is better in standard speech, shouldn’t technical language follow the same guidelines? Let’s examine some passive voice examples in the software domain.
The process was terminated.The child windows will receive a resize message.The script has returned an exit code.The memory block is being moved.
I’m going to try to rewrite each of these in active voice to understand what can go wrong.
Passive voice use is quite common in engineering circles. And if you’re a writer, editor, or marketer who works with engineers, no doubt you’ll agree.
Passive due to uncertainty
The process was terminated. Writing this in active voice might give us something like:
The OS terminated the process.
That’s technically correct since the OS is in charge of running the app and hence will be the agent terminating the process. But it’s pretty vacuous though as well as a bit misleading, since the cause of that termination is absolutely crucial. Did the process terminate because of a segmentation fault? Did it finish its work successfully? Perhaps another process killed it?
We don’t know, and that’s the first reason passive voice is used in engineering-speak: uncertainty. A process termination could mean a successful run, a detected failure condition, a fatal crash, or an impatient user.
Passive voice allows the event to be described without requiring knowledge of the agent causing the action. Sometimes that is essential because we just don’t know. Maybe we want to know, and we will know after much more investigation, but we don’t at the current time. Other times, we don’t know but we don’t need to know and may never find out.
The sentence could be rewritten actively in several ways if you can supply the missing information.
- A successful return from the main function terminated the process.
- The process terminated itself through a failed assert statement.
- A segmentation fault terminated the process due to an undiscovered bug.
- The user terminated the process because it took too long.
These sentences all have drastically different implications. Leaving the active voice subject out is a much better course of action rather than arbitrarily picking a dangerously misleading alternative.
Passive due to unimportance
The child windows will receive an resize message. Moving on to the next example, how would we write this in active voice?
The windowing framework will send a resize message to the child windows.
It sounds a bit stilted because understanding who’s sending the resize message is not relevant information. Saying that it’s the windowing framework puts focus on a component that really doesn’t matter to the programmer, while using passive voice stresses the unimportance of the acting agent here.
That information is unimportant because the programmer doesn’t care if it’s a parent window or a windowing framework or another child window that actually ends up sending the message – those are all implementation details. The key bit is that she knows that a resize message will be sent, and it’s going to be sent to the child windows.
It would be like saying “I’m going to give you your pay check, and the paper that the check is written on comes from the Weyerhaeuser paper mill.” It’s proper English, but – um – but why are we talking about that last part? Leaving out irrelevant information adds to clarity.
Passive voice allows an event to be described without requiring knowledge of the agent causing the action.
Passive due to obviousness
The script has returned an exit code. Write this in an active voice and you get:
The shell got an exit code from the script.
This is really not necessary, and even a bit intrusive. Do we need to say that it’s the shell that gets the exit code? That should be clear because the shell is what executes the script. Mentioning the subject (the shell) can make an engineer unnecessarily think there’s something important or interesting to pay attention to regarding the shell when there isn’t. Here’s another reason for engineer passivity, which is leaving out obvious details. At least, those details that are obvious to the intended reader, allowing them to focus on the relevant information.
Again, the inclusion of obvious details can be jarring. It’s like explaining to a customer why you are going to put a scoop of ice cream in a cone rather than in their hand. Forcing extra information into the conversation that’s understood seems simultaneously pedantic and confusing.
I know the argument from my editor friends here. How do you know the reader knows the omitted details you take for granted? That is a good question. In writing to a technical audience, you have to make some base assumptions on knowledge level. If it’s an introductory “For Dummies” piece, maybe the suppressed subject makes sense to include. However, I’d argue that if the audience really only has a cursory grasp of the material, they are already drowning in technical details. Adding more details that they don’t already know probably won’t make the passage any more clearly understood.
Using passive voice stresses the unimportance of the acting agent.
Passive to emphasize action
The memory block is being moved. What does this look like in active voice?
The library allocator is moving the memory block.
It’s true, however, it muddles the context that the memory block is being moved which might have important implications if there are any pointers to this block stored elsewhere. Introducing the actor obscures the focus of the sentence, which is intended to emphasize action on the sentence’s object, and in fact has an inverse effect of clarity.
One unfortunate part about engineers using passive voice is that none of the reasons I’ve identified will be inherently clear to a non-technical reader.
Only as passive as necessary
Continually navigating these nuances results in passive voice that is pervasive throughout engineer-speak. As engineers, we hardly even recognize when we’re using it. This also lets passive voice creep into areas where it shouldn’t be.
If I’ve learned anything from working so closely with English experts over the years, it’s that clarity in writing is of the utmost importance. That also means you should always have someone else read your work. Things that are crystal clear to you aren’t always clear to the reader. My writing is always better when Nancy challenges me about the implied subject of my sentence or asks about missing details I felt were obvious to the reader. Sometimes they are, and sometimes they aren’t.
One unfortunate part about engineers using passive voice is that none of the reasons I’ve identified will be inherently clear to a non-technical reader. An editor might think that they’re adding clarity by introducing the subject, but an engineer reading that revised copy may think that the meaning is unclear, misleading, or outright wrong. (At the very least they’ll know a non-technical editor had the last say before posting or publication.) But trust me when I say you don’t want engineers editing the copy – unless of course you want the piece to be festooned with exclusively technical jargon and lots of passive voice.
If you’re writing technical content, expect that you will need to use passive voice to make your text as precise as possible. There are several reasons why passive voice and engineering intent go hand in hand. How do you prevent everything from becoming passively convoluted? The most powerful writing combination is an engineer and an editor that each understand and respect the other’s strengths and work together to create copy that uses passive voice only where needed. And only as passive as necessary.
The battle isn’t over because I know Nancy doesn’t agree with my stance here. I’m just waiting for her rebuttal…
About the author
And let’s not forget that using the passive means you can avoid saying:
“YOU should have done this last week.”
Ah yes – avoiding personal responsibility. That’s always a good reason!
Your second and third examples are not passive.
The child windows will receive a resize message.
The script has returned an exit code.
Both active. Passive voice requires a “to be” form with a past participle.
That’s not my understanding: it’s when the object of an action is the subject of a sentence.