Re: Manual and Online Help

Subject: Re: Manual and Online Help
From: "Margaret A. Smith" <msmith -at- aros -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 04 May 2001 10:44:40 -0600

The problem lay in the fact that the text, regardless of where and
how many times it appeared, was poorly-written and unhelpful. If it was
accurate, complete and helpful, then it would've been moot that it appeared
the same way four times--it would have helped you wherever you would have
looked for it.

This is the crux of the matter. We're all basically users of the same or similar tools we document. We've all experienced the "seething" when we seek a nugget of information and find only circuitous descriptions or half-baked, vague explanations that lead nowhere.

I'm guilty of it; I suspect we're each guilty of it---"it" being poorly written documentation, for whatever the reason. Personally, I think it's impossible to anticipate every type of question from every type of perspective that our readers are coming to our product with, regardless of how diligently we analyze our audience and their tasks. (That's why I scoff at the "software solutions" available on the market to automatically generate documentation. Think how rich *that* material must be, in whatever format.) Anyway, yes, the choice of delivery medium is important. But the basics are the basics, and all the tools and cool stuff in the world won't make up for inadequate information-gathering, poor writing, and lack of concern.


And that's why I think

"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


*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See or 800-463-6627 for more about our solutions.

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: Q: Framemaker vs Webworks Standard vs Webworks Professional
Next by Author: RE: Interviewing Subject Matter Experts
Previous by Thread: RE: Word .dot files
Next by Thread: RE: Manual and Online Help

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

Sponsored Ads