Re: Oh those tender users

Subject: Re: Oh those tender users
From: Mike Stockman <stockman -at- jagunet -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sat, 30 Dec 2000 11:33:26 -0500

On 12/29/00 9:45 PM, Michael West (mbwest -at- bigpond -dot- com) wrote:

>Thus spake Andrew Plato:
>>> Good writers [...] educate the user rather than instructing them.
>To which I say: May the gods deliver me from tech
>writers who want to "educate" me rather than tell me
>what I need to know.

Hmmm... I understood Andrew's comments to be the difference between
telling the user what to do, and explaining why the user needs to do it.
I vastly prefer the latter, both when writing and when reading a manual.
Here's an example:

Instruction: Enter the customer name in the Name field.

Education: Enter the customer name in the Name field, using up to 64
characters. Customer representatives will use your entry in all
transactions to locate and assign data to the customer, and it appears on
all customer reports as well.

In other words, the first example told the readers what they "need to
know," while the second told them why they should care at all.
Documentation like my first example is all too common, and never fails to
irritate me. Documentation like my second example is a poor example of
what I try to write for most projects.

Hope this helps,

stockman -at- jagunet -dot- com -- AOL and AOL Instant Messenger:MStockman

Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY. or 800-646-9989.

Sponsored by an
anonymous satisfied subscriber since 1994.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: Revision History in Readme?
Next by Author: Re: Oh those tender users
Previous by Thread: Re: Oh those tender users
Next by Thread: Re: Oh those tender users

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

Sponsored Ads