: Instruction manuals: should the end-user be addressed directly (passive vs imperative)? Manuals come with virtually any appliance, and they typically target the end-user. Among other things (legal

Vote Up Vote Down

Recently, my favorite documentation style is the one promoted by the Pragmatic Bookshelf, a major technical publisher. The PB authors must structure their books as conversations with their prospective readers. The authors must clearly indicate who should do what, and refer to the reader either as "us" (at the instructional phase) or "you" (at the exercise-"do-it-yourself" phase).

(0)

Vote Up Vote Down

Passive voice gets a bad reputation. We're taught to avoid it at all costs. For the most part that's correct, too. It's dull, slows the sentence, and is often vague. If you're writing end user documentation, you should have a style guide and follow it. There's nothing wrong with active voice and even using "you" as long as it's the style you want, along with the tone and intent.

Passive voice has a place, too. Mostly it emphasizes the action, not the actor. In your example you could add "Living animals are not to be placed inside the microwave under any circumstance." The three sentences each have a nuisance that the writer has to decide among.

I advocate passive voice in API documentation to be clear about the actor.

(0)

Vote Up Vote Down

Use direct, simple, clear, imperative instructions.

Passive voice and subjunctive make your language unclear and complicated for an international audience. Luckily in this respect there is no argument among the various schools of thought. For details, peruse the following style guides. Both make very instructive reading.

The IBM Style Guide is my reference of choice, when in doubt:
IBM Style Guide

Microsoft's own version is a little more controversial but some companies insist on it:
Microsoft Manual of Style

(0)