Re: Online Documentation. New! Improved

Subject: Re: Online Documentation. New! Improved
From: "Huber, Mike" <Mike -dot- Huber -at- SOFTWARE -dot- ROCKWELL -dot- COM>
Date: Thu, 17 Oct 1996 12:30:35 -0400

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

Previous by Author: Re: FW: Everybody's a Reviewer
Next by Author: Re: Tech writers' salaries
Previous by Thread: Re: THANKS: Re: HELP!!! Initialism advise needed pronto!
Next by Thread: Re: Online Documentation. New! Improved

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

Sponsored Ads