Long post on passive voice

[Arthur Comings <atc -at- CORTE-MADERA -dot- GEOQUEST -dot- SLB -dot- COM>]

> When is it okay to use the passive voice in documentation?



Can I rephrase the question to "What does passive voice let you
accomplish?" ? This avoids the implication that passive voice (can I
call it PV from now on?) is somehow Bad, but that the people who make
the rules will let us get away with it in certain instances.


PV obscures the fact that most things happen because someone or
something takes an action that accomplishes something. In the PV
universe, things happen by themselves somehow -- people don't do things
that have results. If that's the scene that you want to set with a
piece of writing, PV is perfect.

If your boss comes in and says, "We somehow inserted a bug into the
code three days before we released it -- I can't believe it!" and you
have to communicate this fact in a release note, you can't say that;
it's too direct. In the first place, your boss would probably say, "A
bug got into the code," using active voice to imply that something (the
bug) made an active effort to penetrate your code.

But how can you phrase this? PV is the first choice if you want to hide
a perpetrator. How about "A bug was discovered three days before
release." Well, that fuzzes up the actual finding, but as with most PV,
a reader who thinks about it long enough will start to wonder who was
involved and how it hapened.

You could just say "There is a bug . . .", which doesn't provide any
information about who discovered it or how it got there. If that is
what you want to do, PV is the right tool.  You may decide that who did
it or how, or whatever, is irrelevant. If your reader agrees that they
couldn't care less about HOW things happened, they'll be greatful that
you didn't drag in a long story.

But in most of the technical documentation that I've had to write,
there are a lot of things happening -- buttons to be clicked, programs
interacting, dialog boxes and menus being displayed -- and I like to
let the reader feel in control and in the loop as much as possible.

I can't think of any good examples; I've got to take a quick peek
at one of my manuals.

The first line on page one: "You must create a map definition before
you plot a map." Not "A map definition must exist before a map can be
plotted." Somebody's got to do it -- why not cop to that fact?

But two lines down, "The data that makes up your map is grouped in
overlays . . ."  -- Well, I could have said "We have grouped the data
. . . for you," but it's not relevant. Use PV to get the facts on the
table when the actor is irrelevant.

Whew! I've got to do some work today, but back to our example before I
close. If you have found a bug and have to say so, you can try to PV
your way out of it, or you can take the bull by the horns and use
active voice to indicate activity on the part of your company: "While
testing the Blotzo module under . . . conditions, our Quality Assurance
department discovered that when you . . . the modulation generator may
provide an incorrect value. Here's the workaround for the problem:
First, . . ."    Active, eh?


Those are the tools; you get to decide what you want to accomplish.


Arthur