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.
Should we (the Publications department) continue to use the
passive voice in certain areas of our software documentation=20
if it is the best way to convey information to the reader, and=20
perhaps the easiest way for the reader to understand the information?
We have received several comments from different judges in the=20
local STC pubs competition criticizing our use of the passive voice
in one specific usage in our manuals. We genuinely appreciate
the comments we receive from the judges each year after the
competition and our documentation improves each year due in part
to the judges' feedback.
We all realize that it is generally a "no-no" to use the passive voice
in procedure-oriented manuals (we document software), but we
think it's the best way to go in the instances we use it. Like I said,
we usually implement many of the judges' suggestions, but in this
instance, even though we received the same comment several times,
we are concerned that the judges are reading the manuals from
a writer's standpoint (where the passive is "wrong") instead of from=20
a user's standpoint (where the passive may clarify further). We're
looking for more opinions, and I know this is a group with opinions! :-)
The specific usage is this (occurring in procedures where there
is a step and then a result below it telling the reader what to
1. Click Options.
o The Options dialog is displayed.
The issue is with the phrase "is displayed." Here are the options we've
The Options dialog displays. (displays what?)
The Options dialog opens. (opens what?)
The Options dialog appears. (appears out of thin air?)
<Product Name> displays/opens the Options dialog. (wordy!)
We also realize that this is a small issue to be concerned with, but
we've been receiving this comment for a few years now, and we want
to make sure we're considering all of our options. Anyone have any
suggestions? Oh, removing the whole result phrase isn't really an
option for us--that would be the easy answer. :-)
Feel free to send responses directly to me at kirstin -at- intercon -dot- com
InterCon Systems Corporation