TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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,
----->Mike
________________________________________________________________
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. http://www.weisner.com/training/dreamweaver_help.htm 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 http://www.raycomm.com/techwhirl/ for more resources and info.
