What do you want from help? (was: Do online helps have chapter numbers)

[Geoff Hart <ghart -at- videotron -dot- ca>]

Jens Reineking wondered: <<What do you expect from a good online help?>>

I complained about the quality of online help in a previous message, so 
I suppose I should put up or shut up. Here are a few things I commonly 
find that annoy me to the point of going out and buying a third-party 
book on the software:

- I've yet to see an HTMLHelp implementation that was as easy to use 
and as effective as classic WinHelp. That's doubly true when the help 
is implemented using frames, so that I have to click between panes with 
my mouse before I can scroll. Adobe help particularly annoys me of 
late.

- Lousy indexes. Indexing is an art and a science, and although it's 
true that any index is better than none, it's also time we realized 
that hiring a good indexer is not a luxury. At a minimum, indexes 
should cover every topic (most don't) and should include many synonyms 
for each entry. I have a much better than average vocabulary, yet I 
can't count the number of times I've been unable to find a topic under 
half a dozen different synonyms--all the kinds of words we use daily 
here on techwr-l. Without knowing the one word that the techwhirler 
used, I had no way to find the topic.

- Structure is often vestigial. Yes, it's true that much online help is 
contextual and not part of any linear structure, but there are always 
obvious hooks on which we can hang a structure. For example, why do 
help authors so rarely offer an easy way to browse by (for example) 
menu name so I can click down through the list of menu-choice 
combinations? (I end up using the index, which is fine when the index 
has the appropriate entries.) I'd like to see more "theme" areas, such 
as "characters/fonts", that provide a table of contents to all topics 
that fall under that theme. Instead, most related functions are 
scattered under several different headings. Folks, tables of contents 
are cheap. Why don't we create more of them than just the automated 
master TOC?

- Missing content: There are rarely overviews of the software's 
metaphor and how to work within that metaphor to get things done. Where 
there are copious descriptions of all functions, there are no "this is 
how you assemble all those functions to accomplish the following core 
tasks" types of topics. There is almost never any help of the kind 
"don't use this function to accomplish task A; use function B instead 
because it's more efficient". There is rarely any help of the kind 
"there's a problem with the way this function is implemented, and 
here's how to work around it".

- Navigation tools are often primitive, and restricted to only the 
icons/buttons present in the help engine. There are rarely any 
breadcrumbs ("you followed this path to get to the current topic"), 
forcing me to retrace my path manually, and rarely any indication of 
where a topic fits within the context of larger (broader) topics.

- Text is often clearly written, but useless. The most common reason is 
that the author never bothered to ask the questions I would ask and 
therefore never attempted to answer my questions. (I recommend using 
the five W's approach combined with personas to help prevent this kind 
of problem.) And, of course, there's still a pile of poorly written 
text out there.

- Cross-references are minimal or absent. I recall once trying to find 
out about form fields in Word, and only being able to find information 
on Web forms. Now let's be blunt about this: How many people use Word 
to create Web forms? How many use it to create Word documents with form 
fields? How many techwhirlers would create a help topic that refers 
only to Web forms, with no cross-reference to any other kind of forms? 
Sheesh.

- Formatting has improved greatly, but it's still often inflexible and 
of poor legibility. I particularly despise help systems that don't wrap 
the text when I resize the window to let me see the help system and the 
application simultaneously. And don't get me started about PDF for 
help. <g>

- Worst of all, help systems are still most often a remedy for poorly 
designed software with unusable interfaces, cryptic onscreen labels and 
affordances, seemingly random layout of onscreen controls, and so on. 
If we have to live with this kind of software--and we will for some 
time to come--can't we at least embed the help in the interface instead 
of forcing users to leave their task (the application) and figure out 
where the help is hidden in a second application (the help viewer)?

Give me an hour and I can probably double that list, but I think I've 
made my point. Before you ask, I've been guilty of several of these 
sins myself. I do recognize that in real-world work situations (such as 
when I was the sole help author, and that function was added on top of 
my real full-time job, which was editing and translating), it's not 
possible to do it all. But folks, we could surely do much better than 
we've been doing.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:
http://www.webworks.com/techwr-l

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.