Technical Documentation Voice Preference : "Active Voice" - "Passive Voice" - A Mixture of both

We are working on a technical documentation project which includes the rewriting, modernization, restructuring, enrichment of the content. I'm doing the content rewriting and translation parts of the job and my voice preference has always been on "passive" but sometimes the urge to switch to the active voice becomes hard to resist. I'm finding it hard to explain to the project leaders, too, because they do interfere from time to time to the content and they always tend to switch to active voice. Would using both active and passive voice in different sections of technical manuals, training documentation, service manuals etc be a bad choice? Are there any styling guides on technical documentation which cover this topic?

4 Answers 4

Whatever results in the less convoluted and easier to understand syntax.

Usually people find it easier to understand active voice. Even research articles are today usually written in active voice and avoid confusing self-reference-avoidance (do: "We conducted a study. ", don't: "A study was conducted . " [by whom?]). Machines are operated by persons, they are not "being operated" by a mysterious force.

The APA Manual – which, admittedly, aims at scientific manuscripts, but is often more widely applicable – has this to say about passive voice:

. the passive voice suggests individuals are acted on instead of being actors ("the students completed the survey" is preferable to "the students were given the survey or "the survey was administered to the students"). (p. 73)

Dangling modifiers have no referent in the sentence. Many of these result from the use of the passive voice. By writing in the active voice, you can avoid many dangling modifiers.

Correct:
Using this procedure, I tested the participants. [I, not the participants, used the procedure.] (p. 81)

Incorrect:
The participants were tested using this procedure.

But the passive voice is a valid mode and has its uses, too, of course:

The passive voice is acceptable in expository writing and when you want to focus on the object or recipient of the action rather than on the actor. For example, "The speakers were attached to either side of the chair" emphasizes the placement of speakers, not who placed them—the more appropriate focus in the Method section. "The President was shot" emphasizes the importance of the person shot. (p. 77)

Thanks for the APA reference. I think I'll have to convert some of my sentences back to active voice and check which one fits better. There are sections which need to be passive because they need to focus on the object.

By all means do not forcefully avoid passive voice where it does the better job. Language is a flexible tool and needs to be used flexibly.

Active voice is usually the way to go in technical documentation for the reasons you gave, and one more: such documentation is usually best written in imperative voice, and imperative + passive is a bad combination.

Active voice is the appropriate choice for all types and sections of technical documentation, and for training and service manuals.

The Microsoft Manual of Style is used by professional technical writers.

The 4th edition (2012) says:

• To avoid a wordy or awkward construction.
• When the action, not the doer, is the focus of the sentence.
• When the subject is unknown.
• In error messages, to avoid giving the impression that the user is to blame.

My preference is for passive voice for reference material, some active for tutorials/howtos and whatever is easiest to understand for instructional or theoretical overviews. For example a mechanic changing a tire will check the manual for inflation pressure and lug torques (reference), a teenager will want a youtube video (howto), but an engineer will want to know why (theoretical overview, then reference)

Thanks for the details. Could you please elaborate more on your voice preferences. I'm completely lost here and it would really help me to find some reference points. I can give details about the manual sections that I'm working on.

Passive voice always sounds more 'professional', but a big reason people write that way by habit is because they want to avoid the subject - the actor. If you have an error message all about how the file templates/banff.html isn't found, it sounds goofy to use the first person, as if the software is speaking: "I cannot find the file templates/banff.html" Running through a bunch of alternatives, often feels similarly strange. So, we avoid stating the subject by using the passive voice: "The file templates/banff.html cannot be found."

But imagine that you're reading instructions about making your way through a bureaucracy. You read this sentence: "The application then has the applicant's license and registration number filled in." Are YOU supposed to fill them in? Or does it happen automatically? Are the numbers filled in for you, by someone in the bureaucracy? Whoever wrote it left that detail out.

I have had situations like that, and I continue reading forward, keeping the question in my mind, hoping I'll get a clue further on down as to whether I'm expected to do it or not. Everything I read has to be doubled: "If I fill in the numbers, then that means. but if they fill in the numbers, then that means. ". I've had many situations where I run into yet another similar ambiguity, and I have to carry around three or four cases in my head, plowing through the instructions, hoping for some clues that sometimes never come, because the author continues to write passive voice. Every passive sentence could become one of these fork situations that adds to the reader's mental load.

Remember, also, that nobody complains about bad documentation. They don't want to look stupid, they ask somebody, defeating the whole purpose of the docs you wrote. So just cuz you've done a lot of writing with passive voice, doesn't mean it was a good idea to do so.