The "too familiar" problem?

Subject: The "too familiar" problem?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 13 Nov 2000 10:11:04 -0500

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 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.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"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. or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more 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 for more resources and info.

Previous by Author: Sentence structure?
Next by Author: Significant digits?
Previous by Thread: Re: The "Too Familiar" problem
Next by Thread: State of the industry (was Re: Appalling English)

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

Sponsored Ads

Sponsored Ads