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.
Lois Patterson observes that <<...traditional context-sensitive Winhelp-type
solutions do not seem very practical on the Web... I have yet to see any Web
applications that involve field-level help.>>
Web applications are currently at much the same stage of maturity as
prehistoric computer systems, with no online help or a noncontextual help
system. There's no reason why that should be the case. All you need to do is
add an icon of a question mark right beside the field, and make it an image
map so that anyone who clicks on the icon is taken to an HTML page that
explains the field. If you set the new page so it opens in a second window
(rather than loading in the same window and replacing the existing page),
you have the functional equivalent of WinHelp, and it's sufficiently easy to
build that you don't need any tools more sophisticated than your current Web
page editor.
<<But what type of help system should a web-based application have?>>
My not so humble opinion is that you should build the same kind of help
system as for any online application, only better. Better? Well, if you're
lucky, you're the one who designed the Web interface, and that means you've
got privileged access to the developer and can probably persuade her to make
the necessary design changes. <g> The help system should consist of two
components: the field-level help I've just mentioned (perhaps supplemented
by an overall help page for the dialog box as a whole), and carefully
designed affordances. Affordances are those lovely clues such as "type your
phone number here (numbers and hyphens only, using the format 123-456-7890)"
that tell users clearly what you expect of them. You can supplement these
text labels for each field with pick lists, popup menus, radio buttons, and
all kinds of other tools that guide the user in making their selection or
entering data.
<<The help web pages can be created in a program like RoboHELP, ForeHelp, or
Quadralay WebWorks, and involve a Java applet to index the content (so the
help system can also be viewed separately).>>
Avoid the Java unless you know your audience very well, since that
immediately creates all kinds of browser compatibility, security, and
response speed issues. That's probably an unnecessary level of complexity.
If you've created the help pages for each field or dialog box, you need only
create a page entitled "Help table of contents" that links the help system
together in a logical manner. If you need to create an index, consider using
an inexpensive tool such as HTMLindexer (http://www.html-indexer.com/).
Sometimes the simple approach really is good enough.
"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer
