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.
Subject:Re: Online Documentation vs. Help From:"Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM> Date:Wed, 10 Dec 1997 12:10:24 -0800
> Ben asked,
>
> <<<<<<<<<<<<<<<<<<<<<<<
> How would you pithily explain the differences between on-line
> reference documentation and contextual help to non-technical
> communicators?
> >>>>>>>>>>>>>>>>>>>>>>>>
And Ron answered,
>
> ...Horton says you can't just dump documentation into a help file
> and expect a result that users will appreciate. He says that a Help
> file is a totally separate "thing" that needs to be carefully thought
> out and developed.
>
> ...I would love to hear what other people have to say...
Although you can't just dump paper docs online and call it a help file,
you can just dump paper docs online and call it online docs. Mostly it's
a matter of setting user expectations, but there's also some forethought
and planning involved if you want to keep the book usable.
Ideally, a help file provides "just in time" information on program
operation, answering the user's questions appropriately each time it's
accessed. It should contain contextual information (information on
fields/dialog boxes) and may also contain procedural information,
definitions, and some conceptual information.
Because the typical user accesses a help file for between 30 seconds and
2 minutes at a time, a well-constructed help file is pithy itself, answering
but a single question per topic -- and, of course, that question should be
the one that the user is asking at the moment.
So, then... A pithy shot at the differences...
Online help provides concise, just-in-time information on software operation
and is constructed in accordance with platform conventions and standards.
By convention, online help is connected directly to the software via menu
items, help buttons, and/or function keys.
Online documentation (or reference, if you prefer) provides comprehensive
information for the software and may or may not be connected directly to the
software. Online documentation is frequently structured like a book, but
whether or not it uses the book metaphore, its structure is less rigidly
defined by platform conventions and standards.
