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.
David Downing observes that <<One reasons that developers/programmers don't
do such a hot job of documenting their own software is that ... they can't
"back off" and look at it through the eyes of the poor user who's just
taking it out of the box and doesn't know diddly about how it works. Well,
I'm finding writers can end up in the same boat. I have to write some very
general introductory material for some software I've been documenting at a
detailed level, and I'm having trouble looking at it from the outside.>>
It's never really possible to approach something with naive eyes once you've
lost your innocence <g>, but you can at least fake it and still achieve
reasonably good results. One thing that often works is to start by listing
all the typical tasks you'd perform with the software and the general steps
you'd take for each task; that should be the easy part, since you've already
done that work when you created the detailed documentation. Now comes the
hard part: ask yourself _why_ you are doing these things with the software,
and what overall philosophy or attitude or knowledge might be guiding the
approach you've already documented in the detailed steps. In short, figure
out the needs of the users, and how the software's overall metaphor relates
to satisfying these needs. This is knowledge that newcomers won't have and
desperately need to know; in effect, your introductory material becomes a
user's guide to the user's guide by providing the overall context within
which the users will use your detailed instructions.
The tough part lies in really understanding your audience. Silly example:
Are they engineers who already understand the overall process of building a
single-stage-to-orbit aerospace plane, and merely need your software to
facilitate the task, or are they a bunch of venture capitalists planning to
develop a virtual plane as part of the latest getrichquick.com scheme? Do
they already understand the basic design process, or do you have to teach
them design too? Your own software will have various parallels to this
example, and you'll have to use those parallels to guide your approach.
"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more http://www.SolutionsEvents.com or 800-448-4230
---
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.
