Re: Some Help With Re-phrasing

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.

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Author, _Practical Software Requirements: A Manual of Content & Style_
http://www.amazon.com/exec/obidos/ASIN/1884777597/002-3618777-1904817
http://www.manning.com/Kovitz

From ??? -at- ??? Sun Jan 00 00:00:00 0000=




Previous by Author: Re: "based" hyphenations
Next by Author: Action-response pairs
Previous by Thread: Re: Some Help With Re-phrasing
Next by Thread: Re: FWD: Consultant challenges/editing


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


Sponsored Ads