TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
