: 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,

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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:

In general, use active voice. Active voice emphasizes the person or thing performing the action. It's more direct than passive voice, which can be confusing or sound formal.
Use passive voice sparingly. It is all right to use passive voice in the following situations:

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.

(0)

Vote Up Vote Down

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)

(0)