Recently, I was proofreading a technical design document written about a system that was unfamiliar to me. It described the flow of execution through a fairly complex system. I found it more difficult to follow the design than it should have been, but I wasn’t sure why. After some thought, I narrowed down on the culprit-like many technical documents, this one was written using a fair amount of passive voice.
“The passive voice is a grammatical construction (a “voice”) in which the subject of a sentence or clause denotes the entity undergoing an action or having its state changed.” (Wikipedia) For example, an active voice sentence would be “I dyed the cat green”, while examples of passive voice would be “The cat was dyed green by me”, or even just “The cat was dyed green”. Notice that in the last of these sentences, you never learn that it was me that did the cat-dying; I’ve managed to forgo letting you know how I was involved at all. I think many of us in technical fields have learned to write this way throughout our careers. From being asked for impossibly precise estimates to being asked if certain unknown tasks were possible- then being held to those guesses, I think it’s become a defense mechanism for many of us to distance ourselves from the things we are trying to communicate.
There’s a problem with this natural instinct to fall back to the safety of passive voice: it can sabotage our attempts at clarity. Following the flow of an unfamiliar technical topic is often *hard*. The person trying to absorb knowledge is carefully trying to follow the process from step to step, somewhat like a driver trying to make his/her way to an unfamiliar destination using printed-out google map directions. A passive voice sentence in a description of a complex technical algorithm can feel analogous to ripping out the middle steps of those google map driving directions. The result is something like this: “X performs an action, sending data to Y. Y then transforms the data. Action Q is then performed” This leaves the reader asking, “Why was Action Q performed? Was it X, Y, or something else entirely that performed action Q? How many intervening steps are invisible/implied? Is Q even related to X and Y?”
Another reason people use the passive voice is because they aren’t sure about some of the details at the time of writing, so passive voice provides a way to keep the document smooth and professional-sounding, while providing the illusion of continuity. I would argue that if the goal is to communicate clearly, actually stating and explaining the uncertainties is going to be much more helpful to readers. Consider this revised version of the previous phrase: “X performs an action, sending data to Y. Y then transforms the data. Then, either Y or X performs Action Q -we’re not sure which, it all depends on what turns out to be less resource-intensive, and we haven’t finished that research yet”. This new version may feel more wishy-washy, but it is easier to follow, and it communicates some important uncertainties that the previous version glossed over.
Maybe discussing a grammatical point seems to be a bit off-topic or even pointlessly fussy, but use of the passive voice has a real effect on the readability of explanatory/design documents. (In comparison, I doubt the lay/lie grammar issue or even use of a word like irregardless is going to cause any real readability problems if they show up in your document) Most programmers have to write this kind of document now and then, and it is in everyone’s interest that we write these documents so others can understand what we’ve written. A little thought about wording can go a long way towards making documents a means of communication instead of another reason for confusion.
Leave a Reply