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.
"Mike Stockman" wrote...
> 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.
That's exactly correct, Mike. Most writers document only the raw basics of a
product: click here, point there, enter here, push this. They rarely look
beyond the pointing and clicking to explain why things are done.
Last year my company rebuilt a doc set for a big database company. The
previous writer bitched and bitched about how the engineers and the project
manager didn't respect her work. No surprise, her work was pure crap. There
was absolutely no explanation of what the product could do. A typical line from
her manual:
"CURSORS: Enter the cursor value."
DUH! What is the cursor value? What does it do? Where do you get it from? She
clearly had no idea how the product or databases worked. She fought all the
time with the engineers over the user interface and put little if any effort
into the manuals. In every meeting she would declare that SHE knew what the
users wanted...which was absurd because she didn't know ANYTHING about
databases and the readers were all database administrators.
In her quest to be an advocate for the user, she wasn't giving the readers what
they NEEDED.
Which is my big issue. How can you be an advocate for the users when you don't
know WHAT to give the users? Readers overwhelmingly want rock-solid, accurate
information. They don't care about which tool you used or how you got the
information on the page.
If you can't give your readers accurate, detailed, insightful technical
information you're not doing them any favors and you're not a good TECHNICAL
writer.
Andrew Plato
__________________________________________________
Do You Yahoo!?
Yahoo! Photos - Share your holiday photos online! http://photos.yahoo.com/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
