Passive voice is killing your design documents

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.


Posted 08-11-2010 8:02 PM by Anne Epstein
Filed under: ,

[Advertisement]

Comments

dave.t wrote re: Passive voice is killing your design documents
on 08-12-2010 10:51 AM

Anne, this is a great article describing clearly an issue that's hard for non-grammar types to grasp.

But I think it goes beyond just writing technical documents - I had my wife proofread a cover letter & resume I put together and she pointed out how much passive voice I had used.  By rewording it it made me sound much more authoritative and empowered, as in "I instituted this policy" versus "Policy was instituted".

I would imagine that most developers spend a lot of their time writing things besides documentation and that things like this will help there as well, such as emails and performance reviews!

Stig Bakken wrote re: Passive voice is killing your design documents
on 08-14-2010 5:11 AM

Wouldn't a more appropriate title be "Design documents are being killed by passive voice"?

John V. Petersen wrote re: Passive voice is killing your design documents
on 08-16-2010 9:23 AM

This was a great post written by Anne!!

Hold on...sorry about that!!

Anne wrote  a nice post!!!

The problem with passive voice is that it can obscure clarity. If your goal is to bury something in the hopes that it may be glossed over, then passive voice can be your friend.  It's one of the reasons legal documents are riddled with passive voice.

The ant was stepped on by Timmy.

Timmy stepped on the ant.

A simple example. However,  it takes a little longer (imperceptibly) to decipher the first sentence. Now, imagine if the issue were more complicated - like a design document or a work flow pattern?

However, when you are trying to make a point that is clear and direct..

Oops...there I go again! Let me try it again..

However, when you are trying to make a clear and direct point, you want to rid your prose of passive voice. Almost always, passive voice yields more text. This is where good copy editing counts! Books and magazines are good examples of where passive voice can be a real killer.  

Sounds like a good topic for an open space...

DAMN!!!!!

I mean, sounds like a good open space topic!!!

Anne Epstein wrote re: Passive voice is killing your design documents
on 08-16-2010 11:04 AM

@Stig - Yeah, you got me there :)

@John - Hadn't thought about this from a legal document angle, but it makes a lot of sense.  Considering that it's so important to get things precise in the legal profession, and passive voice tends to obscure missing things, it's pretty disheartening that lawyers use it so much in their legal documents.  

Anyway, I think you have it exactly right, in either a design document or a legal document, if your writing style is such that it's harder for others to understand and you layer that on top of a complicated topic, you are probably creating a serious problem for readers. re: open space- yeah, good idea. Maybe not as narrow a topic passive voice, but it would be great to talk about the larger topic of how to better communicate more clearly in writing.

cheap backlinks wrote re: Passive voice is killing your design documents
on 07-18-2014 7:38 PM

CzeoKW I cannot thank you enough for the blog post.Really thank you!

Add a Comment

(required)  
(optional)
(required)  
Remember Me?

About The CodeBetter.Com Blog Network
CodeBetter.Com FAQ

Our Mission

Advertisers should contact Brendan

Subscribe
Google Reader or Homepage

del.icio.us CodeBetter.com Latest Items
Add to My Yahoo!
Subscribe with Bloglines
Subscribe in NewsGator Online
Subscribe with myFeedster
Add to My AOL
Furl CodeBetter.com Latest Items
Subscribe in Rojo

Member Projects
DimeCasts.Net - Derik Whittaker

Friends of Devlicio.us
Red-Gate Tools For SQL and .NET

NDepend

SlickEdit
 
SmartInspect .NET Logging
NGEDIT: ViEmu and Codekana
LiteAccounting.Com
DevExpress
Fixx
NHibernate Profiler
Unfuddle
Balsamiq Mockups
Scrumy
JetBrains - ReSharper
Umbraco
NServiceBus
RavenDb
Web Sequence Diagrams
Ducksboard<-- NEW Friend!

 



Site Copyright © 2007 CodeBetter.Com
Content Copyright Individual Bloggers

 

Community Server (Commercial Edition)