14

Manuals come with virtually any appliance, and they typically target the end-user. Among other things (legal specifications, part numbers…), these documents contain specific instructions on what to do and what not to do with the appliance.

Should these documents directly address the user (imperative form) or should they be written in passive voice?

Example:

Do not place living animals inside the microwave under any circumstances.

Under no circumstances are living animals to be placed inside the microwave.

What are the different effects of either style?

migrated from techcomm.stackexchange.com Feb 20 '18 at 15:15

  • In some cultures direct instructions are considered rude. – Bookeater Jan 28 '18 at 15:28
  • Some use the active indicative, i.e. Operators [should|shall|must] not place living animals inside the microwave under any circumstances or You [should|shall|must] not place living animals inside the microwave under any circumstances. – choster Jan 29 '18 at 19:26
  • Closely related (but not a duplicate): Why do many manuals and technical documents seem to prefer passive voice? – EJoshuaS Jan 30 '18 at 16:15
  • 1
    Lots of manuals and other technical documentation are badly written. Passive voice has its place, but not in a sentence telling users when to put live animals in a microwave oven. – Robert Lauriston Jan 31 '18 at 0:28
  • Regarding other cultures, I should think that would be handled in localization. Imperative will generally be easier to translate. I am of course assuming the source text is in English. – Charles W Feb 1 '18 at 16:59
15

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

  • In my view it's pretty much the opposite: the Microsoft Manual of Style reflects conventional wisdom while the IBM Style Guide has some eccentric advice, much like the Chicago Manual of Style vs. the AP Stylebook. – Robert Lauriston Jan 31 '18 at 0:23
  • 1
    With active voice and imperative mood, there is little doubt as to who needs to do what. As a reader, I don't have to wonder about the nuances of should and could and would, I don't have wonder who is this mysterious "one", and whether the passive voice implies that I should do something, that it's already been done, or that someone (perhaps the company behind the product) should be doing the thing. – Iva Koevska Feb 5 '18 at 9:41
7

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.

  • 2
    Passive voice is about the thing being acted upon, leaving the actor completely unclear or unmentioned. – Adam Michael Wood Feb 4 '18 at 23:54
1

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).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.