RE: Generally, what do you think of generally?

Subject: RE: Generally, what do you think of generally?
From: Janet Valade <janetv -at- systech -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 8 Feb 2000 10:04:28 -0800


<<Giving examples is good, Janet. However, which is stronger?

"In almost all cases the software will load correctly. If not, then
reinstall the frimfram application."

or

"If the software does not load, reinstall the frimfram
application.">>

This is not the appropriate situation for "In almost all cases", not
the situation I described in my message. In this case, I would do neither of
the above. For one thing, in some cases, software can load but not load
correctly. I would probably document the above procedure this way, depending
on the software:

1. Provide instructions for installing/loading (I can't tell if
these are the same thing from your example)
2. Describe what the user should see so that they know it
intalled/loaded correctly
3. Describe what to do if the software did not install/load
correctly

Following are examples in which "In most cases" is appropriate
Example 1) RJ-45 to DB-25 or DB-9 adapters may be used with RJ-45 cables to
create the cable configurations shown in Figures 3-3 through 3-6. In most
cases, you use "straight through" RJ-45 cables. If you use "crossover" RJ-45
cables, the RJ-45 pins will be reversed. Figures 3-8 and 3-9 illustrate the
difference between the two types, when constructed with flat 8-conductor
wire.
(It is useful information for the novice to know that the straight through
cable is the more usual cable to use)
Example 2) The port server supports up to 30 PVC's. In most cases, the DLCI
number for your first PVC will be the lowest available number--16
(It helps the novice to know that 16 is an okay number. They might be
expecting to see 1. But you don't want the user to think that a different
number is wrong.)
Example 3) The port server can be configured using the XYZ software. If you
use XYZ, the ports are configured automatically and, in most cases, you do
not need to set any parameters manually. Examples of exceptions in which the
port needs to be configured manually, even when using XYZ, are: 1) setting
the electrical interface (RS232, RS422, RS485), or 2) configuring a port
that is not under XYZ control.
Example 4)
The set frame_relay command defines the custom service configuration
specified (Cn) as frame relay and enables it on the specified port (wan or
33). To define custom service configuration C6 as frame relay and enable it
on port 33, enter:
set fr C6 33
You will see the following prompt:.
Type of LMI:
Enter the type of Link Management Interface you have leased: ANNEX_D, LMI,
or ANNEX_A.
Additional prompts, shown in the table below, will appear. In almost all
cases, the default will be the preferred choice. Only change the default
(shown in the brackets) to meet a specific need.
Prompt Information
N391 count [6] number of Link Integrity Verifications between Full Status
Queries.
N392 count [3] number of errors permissible in a N393 time period.
..

<<When I was a fledgling writer, oh so many years ago, I was taught
Accuracy,
Brevity, Clarity. Adverbs add nothing to the ABCs of good
writing.>>

Just out of curiousity, how would you convey the following
information without using an adverb.

Some of the settings become effective immediately, while others only
become effective upon restart or user login.

Janet

Janet Valade
Technical Writer
Systech Corporation, San Diego, CA
mailto:janetv -at- systech -dot- com






Previous by Author: RE: Generally, what do you think of generally?
Next by Author: RE: Generally, what do you think of generally?
Previous by Thread: Re: Generally, what do you think of generally?
Next by Thread: RE: Generally, what do you think of generally?


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

Sponsored Ads


Sponsored Ads