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.
Subject:Re: Some Help With Re-phrasing From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Thu, 22 Oct 1998 13:05:08 -0700
Deborah Cooper asked:
>I'm having a problem with correct wording. I'm trying to convert
>a passive-voice document to active voice. Here's the phrase I'm
>having trouble with:
>
>While the Summary window is displayed, you can double-click
>any entry shown in the Summary window. This action causes
>the system to display a new Job View window for this job.
>
>Its actually (I think) the second sentence that is causing the
>problem. The document consists of many such sentences and
>I'm at a loss as to what to do.
Many others have suggested good ways to reword this in the form
of one sentence. Here are some other alternatives and ideas to think about.
1. If you have many of these sentences, all describing piddly
little tasks that can be done on one screen, make a screen shot
with callouts pointing to each active element on the screen. The
callout could then read, "Double-click to display new Job
Window." Since the callout points to the thing to double-click,
it can just read, "Double-click to open a new Job View window."
Pictures with lines pointing to the things to click are very easy
to understand.
2. The word "entry" is somewhat awkward and therefore something
to avoid if you can. Some other alternatives are "row", "item",
and "element". Better yet, just refer to the job.
3. Any time you find sentences with the word "this" all over the
place ("this action", "this job"), you can probably find better
ways to point to the object. One way is with callouts. Another
is by collecting like elements into a table, like this:
Actions available in Summary window
To... Do...
----- -----
See a job in more detail Double-click the job
Cancel a job Click the job, then click Cancel
. . . . . .
4. If you can possibly help it--and 99% of the time you
can--don't refer to things like "this action". That is, don't
find a cleaner way to refer to it, just don't refer to it at all.
Just say what happens next.
5. "Is displayed" is not bad because it's passive. In fact,
there's nothing wrong with the passive voice, just as there's
nothing wrong with the word "click". The passive voice is wrong
when it deemphasizes or omits something that should be emphasized
or mentioned explicitly, just as the word "click" is wrong when
you want to say something other than "click". However, "is
displayed" is a bit wordy, since you can just say, "In the
Summary window..."
6. Most important of all, why would a user want to open a new
Job View window? A manual should be written from the point of
view of the user, who has work in the outside world to get done.
That is, it's best if you organize the manual around the tasks
that users need to perform, not around windows and buttons. In
this case, the step of opening a new Job View window might recur
many times, as part of many other tasks. For example:
> To postpone a job:
1. In the Summary window, double-click the job.
The Job View window opens, showing the job in more detail.
2. Re-enter the job's Completion Date, or click the
upward-pointing arrow next to it. Each click makes the
date one day later.
3. Click OK.
The Job View window closes.
A classic mistake in technical writing is to give the user a
jigsaw puzzle of micro-tasks, each pertaining to a feature of the
software. Somehow the user is supposed to grasp them all at once
and figure out how to combine them to get some useful work done.
The job of the writer is not to describe the software's
capabilities, but to bridge the gap between the software's
capabilities and what the user needs to do. Often users don't
even know what jobs they need to do, so you have to explain that,
too. You need to say, in effect, "Your job consists of these
tasks, and for each task, I'll show you all the steps that get
the task done." In many cases, these steps should not even be
limited to actions involving the software.
