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.
Certainly, the big immediate problem is the garbage documentation, the
"type the name in the NAME box" kind of thing.
But I think there is an important, but subtle, difference between the
goals of a manual and a help system. When I hit that F1 key, I have a
particular question I want answered. When I open the manual, I may have a
particular question (in which case I'm already unhappy, because the help
system didn't answer it, and if I see the same non-answer, I'm going to
be upset) or I may want to learn something.
The magic help system works like this:
I hit the button and my question is answered.
The magic manual works like this:
I, an ignorant but eager learner, read the book and become an expert.
Things have changed lately. The term "on-line documentation" is no longer
a synonym for "help system," and the manual may not be paper. But the
underlying goals are the same. Where I used to argue that we needed both
books and on-line help, I now argue that we need both high level
documentation and immediate help. Those needs may (in some situations)
be served by online documents, but they are different needs nevertheless.
----------
From: Robert Plamondon[SMTP:robert -at- PLAMONDON -dot- COM]
Sent: Thursday, October 17, 1996 11:03 AM
To: TECHWR-L
Subject: Re: Online Documentation. New! Improved
The problem is not that it's impossible to do good on-line documentation,
but that the flagship products have garbage-scow documentation, and
many people cheerfully salute the flag and emulate the garbage scow.
Sure, you can do really cool on-line documentation. But it's a
fallacy that on-line documentation is all that different from any
other kind of documentation. It has the same goals, the same
subject matter, and the same readers as a paper manual would have.
