RE: Taking active vs. passive voice too far

Subject: RE: Taking active vs. passive voice too far
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 10 Jul 2013 09:58:31 -0400

In my experience, saying that a message might appear, without specifying the precise internal process that triggers it (assuming that only one process might be responsible in a complex application...) is a perfectly normal documentation choice when the customer has no business knowing the inner workings of the application. It might be proprietary "secret sauce", or it might be simply that they can't change the process (or it's outside their scope as users to do so), so they can only affect its inputs.

What might be useful to include, on the other hand, is to suggest real-world actions and situations that might precipitate the message, or describe a class (not necessarily in the restricted, programming sense of "class") of events such that the reader could determine if they are doing something that might cause the message. And then, if it's not obvious ("Doctor, it hurts when I do this." "Well, stop DOING that!!") what to do to avoid the message condition, then offer some suggestions... or the ever-popular "Contact Technical Support at...."

-----Original Message-----
From: Chris Despopoulos
Sent: July-10-13 4:50 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Taking active vs. passive voice too far

I agree with the previous comments -- Turning your statement into an active one is a good idea.  I want to point out that there's more to active voice than setting up a construct that begins with "To do X", and that directly tells the reader what to do.  Active voice compresses more information into fewer words.  A full active statement should identify the actor and the object of the action.  For example, the passive "An alert message displays" only identifies an object.  The active construct, "The foo process displays an alert message" gives more information...  Exactly which process warns for the error state.  The active example is longer than the passive one, but it conveys more information. 


To make a fully active statement, you often have to dig in and find out exactly who or what is performing the action -- not always apparent.  And you often have to find out more details about what causes the actor to spring into action.  This isn't always easy.  In my experience, much of the passive voice that I've seen comes from the writer not doing the extra work, for whatever reason (habit, assumptions, laziness, etc.).  As you go through this exercise, you will probably find instances of this kind.  More than anything else, you should try to fix those -- you'll know more about the product as a result.  And as a result you will be in a position to add more value to the team.

cud



The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
RE: Taking active vs. passive voice too far: From: Chris Despopoulos

Previous by Author: Link checking for offline webhelp
Next by Author: RE: Taking active vs. passive voice too far
Previous by Thread: RE: Taking active vs. passive voice too far
Next by Thread: Re: Taking active vs. passive voice too far


What this post helpful? Share it with friends and colleagues:


Sponsored Ads