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 Sat, 28 Jul 2007 22:58:32 -0700 (PDT), Keith Hood <klhra -at- yahoo -dot- com>
writes in part:
> Ladies and gentlemen:
>
> I guess I appreciate your being concerned enough to
> tell me you think I'm sitting on a toilet with
> nitroglycerine in the tank, but please,...what I
> need is pointers toward examples of things you think
> are particularly good user documentation.
> Thanks.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Hi Keith,
Unfortunately, there is very little good software documentation of the
sort you plan to produce out there. There are many, many descriptions of
software screens; many, many "How to..." instructions that tell you to
"Enter the desired..." but don't give you a clue what "the desired" might
be for the operation you're working with or give you a heads up that the
settings for "such-and-such" interact with the settings for "so-and-so,"
so both must be set with a particular relationship to achieve "the
desired" result. (And I must say, I cringe whenever I read "the desired"
in software and other docs. It generally is a big red flag, indicating
that the docs are not going to be particularly useful.)
The work I've done along these lines is all proprietary, so I can't point
you toward particular examples, but I can suggest the following.
Your users, like the engineers and scientists I've worked with for years,
dislike and, in practice, have little time for reading. Where ever
possible, use flow charts, quick reference cards, keyboard cheat-sheets,
and the like.
Keep your text short, sweet, and to the point. (Hmmm...a writer who
doesn't like a gazillion words where one will do...I suspect I'll start a
furror with that one.)
If you provide training for your software, sit in on a class and
definitely talk to the trainers. They know what user's need more than
anyone else in the company.
Check your tech support logs. Find out what aspects of the
software/documentation are giving users problems. Knowing the problems
users are experiencing will help you guide them in your new docs so they
don't get into those fixes.
If you can, work with the interface developers to make the software
intuitive. If it takes you 12 pages to describe a simple operation, you
can bet your users will be frustrated, and your tech support lines will
be ringing. The simpler the interface is to use, the better your
documentation will be.
One good piece, in terms of basic instructional writing that I've seen
recently, is the Help Center at ImageConverter Plus. Here's an example: http://www.imageconverterplus.com/help-center/work-with-icp/first-install
ation/ It is all on-line, so the user can't lose the book...it's right
there, available from the application, 24-7. There are some "oddities" to
some of the text on the site, as the program is from a Moscow-based firm.
Nice, very powerful, little utility, if you work with lots of graphics,
too!
You have a good plan for producing some really nice documentation.
Best to you,
ME
Mary Ellen Schutz, your Gentle Editor
Gentle Editing, LLC
www.GentleEditing.net
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is easier to build strong children than to repair broken
men...Frederick Douglass
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
