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 07:50:30 -0800

<<all. What it is is uncertainty. I think that what the programmer
is
> trying to say is "This piece of code does this action 999 times out of
> 1000 but, for some reason we can't figure out, sometimes it doesn't. We
> warned you so don't try to sue us when it happens!" The legal department
> love this kind of CYA writing!>>
>
I don't think this is the usual situation when "generally" type of
sentence construciton is used. More often, I think it is when there are
several options or parameters. Users need to make a choice on the proper
option for their particular use or environment. You are trying to help the
user with some guidance on the option to use, but you can't say absolutely
which one the user should use without knowing the user's specific use or
environment. If most users use the product in a similar way, you document
that use, but try not to make the users who are using it in a non-typical
way think that they can't do what they want to do.

I document network hardware. The users must install and configure a
very complex product. Most users are using it in a normal, common type of
network. But, users can be quite creative in thinking up ways to use your
product that you never envisioned when you developed the product. You want
to include these users in your documentation. I prefer to use construction
other than "generally" however. I consider that a little too vague. I tend
to say things like, "In almost all cases" or "With rare exceptions" or "With
only a few exceptions". If I can, I try to give an example of an exception.

Janet

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





Previous by Author: Re: Summary of Responses: Whirlers and Environments (Long)
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