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. Which Help is the best help? From:"Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA> To:"Techwr-L (E-mail)" <TECHWR-L -at- lists -dot- raycomm -dot- com> Date:Thu, 24 Feb 2000 09:22:08 -0500
Kate O'Neill <<...is trying to decide on the best help technology for each
of several apps (each app can have different help delivery technology).
What's constraining the decision: - One of the products will be run only in
a local Windows environment, but two of the products will be run like thin
clients through web browsers. - The VP of Engineering doesn't want users to
have to download an applet of any kind [or use HTML Help].>>
For the client that runs only in Windows, the answer's easy: use WinHelp.
It's easy to create, works flawlessly (in my experience), and will be
familiar to your audience. I've heard enough bad things about HTML help, and
run into enough frustrations in using it myself (the versions I've used were
abominably slow and had pitiful search facilities) that I second your VP's
recommendation: wait until it's a mature technology. You _can_ do good
things in HTML help, but it's not going to be as easy or as usable as
WinHelp.
<<the two web-based apps will rely on vanilla HTML, but I'm not thrilled
about delivering in vanilla HTML (no search or index unless they roll their
own).>>
The lack of a search function isn't much of a problem since most of them
provide very little help; I've only rarely been able to find what I was
looking for with a search function. Since the applications are Web-based, it
should be trivial to produce true context-sensitive help simply by adding a
hyperlink right beside each field or button; a button with a ? on it would
probably be least intrusive. If you can't persuade the developers to
implement this solution, you could instead design a separate help file that
mirrors the physical structure of the software: this is a sloppy way of
creating context-sensitive help, since users have to find (navigate to) the
context by themselves (rather than just hitting F1 and having the software
figure out the context for them), but if the structure really does mirrors
that of the software, it should be easy for users to navigate to the same
part of the help file as the part of the software they're using. I imagine
you could even use image maps based on screenshots from the software, and
all the user would have to do is click on the appropriate parts of the
screenshot to move to the help for that screenshot. Works for me!
Indexing is another matter, but it's also not rocket science; the hardest
part is choosing helpful, useful keywords. I've discussed the issues
involved in producing a manual index "the hard way" in an article I
published a while back ("Index the web", Intercom, June 1999, p. 26-28), but
you can also have a look at a product called HTML Indexer which takes much
of the drudgery out of indexing HTML; you can download a trial copy from http://www.html-indexer.com/ I've heard good things about it, but actually
working with the copy I downloaded keeps getting pushed further back on the
list of priorities. (Hmmm... perhaps if I spent less time on e-mail? <g>)
--Geoff Hart, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"The paperless office will arrive when the paperless toilet
arrives."--Matthew Stevens