Re: Wordiness and Complete Sentences

Subject: Re: Wordiness and Complete Sentences
From: Steven Jong <SteveJong -at- AOL -dot- COM>
Date: Fri, 21 Jun 1996 14:16:36 -0400

John Russell <JRussell -at- DATAWARE -dot- COM> is lumbered by programmers who want him
to recast his manual using "incomplete sentences." First, John, I agree with
the previous comment that it's your call. However, I'd like to throw in
another few opinions (though certainly not carved in stone).

First, there are sentences and there are sentences. Task steps are usually
best cast as imperative statements. Other constructions tend to run longer;
if you're using them, I might agree with the programmers:

n. Next it is necessary to adjust the amount of memory taken by the
program. To adjust the amount of memory, enter the command
MEMORY XXX, where XXX is the amount of memory, in kilobytes,
that you have previously determined to be appropriate for your
system.

as opposed to...

n. Adjust the memory size of the program, as you previously
determined, by entering MEMORY XXX.

or even...

n. Enter MEMORY XXX to reset the memory allocation.

Second, the level to which you break down task steps can strongly influence
the wordiness of a document. If you describe tasks at what I call the "atomic
level," you'll get very long task descriptions; for example:

1. Click on File on the menu bar. The File menu appears.

2. On the File menu, select Print... The Print dialog box appears.

3. Check the box labeled "Print to file."

This will quickly drive your readers (and you) insane, even if they're rank
beginners. You may wish to describe steps at a higher leve; for example:

1. Select File:Print... The Print dialog box appears.

2. Check "Print to file."

Of course, if your audience already knows how to do the simple things, and
wants to do more high-level tasks, you should accomodate them. A system
administrator might consider a discrete task to be "register new users," and
you might need to document the product using steps no more detailed than
that. Perhaps that's a little extreme, but certainly a mismatch between task
level and audience needs will trigger the sort of remarks you're reporting.

However, if it were me, I would not go so far as to acquiesce to writing
sentence fragments. Professional standards, you know 8^) Seriously, the more
tersely you write an instruction, the more difficult it would be for the
reader to recognize and recover from a mistake. I have seen an engineer write
a configuration procedure including these steps (I am not making this up):

1. Click Close.

2. Press Return three times.

3. Reboot.

(No, these were not the operating instructions for the Holy Hand Grenade of
Antioch 8^) What on earth happens when you click Close? If you press Return
four times or twice, how will you know? Those are terse, incomplete
sentences, but I think the operative word here is "incomplete"!

-- Steve

================================================================
Steven Jong, Documentation Group Leader ("Typo? What tpyo?")
Lightbridge, Inc, 281 Winter St., Waltham, MA 02154 USA
<jong -at- lightbridge -dot- com>, 617.672.4902 [voice], 617.890.2681 [FAX]

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Post Message: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Get Commands: LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "help" in body.
Unsubscribe: LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "signoff TECHWR-L"
Listowner: ejray -at- ionet -dot- net


Previous by Author: Re: Fonts for Online documents
Next by Author: Re: Fonts for Online documents
Previous by Thread: Re: Wordiness and Complete Sentences
Next by Thread: Request for Re-send


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


Sponsored Ads