Context sensitive TOC + content (long)?

Subject: Context sensitive TOC + content (long)?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 27 Jun 2002 15:58:35 -0400

Barb Einarsen reports: <<The development team ... would like to track how
the user moves through the software to the point where they click Help, then
compile a unique help file that contains only items that are relevant to the

Really. Bad. Idea. <g> First off, don't they have more important things to
worry about, like debugging the software, making it run fast, and
stabilizing the interface? Second, are they aware that they're proposing an
artificial intelligence system that somehow manages to read the user's mind
and figure out not what the user actually wanted to do but rather what they
actually wanted to do? Not a trivial proposition, and as anyone who's done
battle with Clippie the Paperclip in MS Office, one that's likely to
seriously annoy the user. ("You seem to be preparing to stick a brick
through the monitor. Would you like me to show you how to do this using
nothing but keyboard commands?") Third, what about the user who needs
related information that wouldn't be revealed this way? For example, I work
my way six levels deep into the "insert index marker" procedure, then
realize what I really wanted to do was create a bookmark--yet the Help file
opens to only reveal information on indexing.

<<They propose: One master help file that opens when called from the Help
menu. Then, many, many individual help files that are individually selected
and compiled together at run time to create a context sensitive help

So that the Help file takes 5 minutes to open each time I hit F1? I don't
think so. If you're going to do something like this, present the standard
help file for the entire documentation, with the current context's topic
showing (i.e., context-sensitive help), but add a list of related topics at
the end of the current topic. Wait a minute... isn't this called a
cross-reference, and don't we already do this when we create help systems?

<<I'm worried that the user will want to see and move through the entire
tree, regardless of where they originially reach the help
file. I'm also concerned that they won't realize there is an overall help
file, and think the only help that exists is what appears.>>

Precisely my concerns. Plus, as you note, this is another whole whackload of
code to debug. Not trivial code either.

<<Can you see pros or cons that I'm missing?>>

The pros are obvious: the developers want to work with you to produce more
usable software, and they're willing to integrate presentation of the help
with the way the user interacts with the software. The good news? You can
channel this energy towards a proven solution that's easier to implement and
that works substantially better than standard WinHelp and its evil
offspring: it's called "embedded help", and in addition to being discussed
periodically on techwr-l, you can find a great article on the topic written
by none other than our listmom and listdad:

Ray, D.S.; Ray, E.J. 2001. Embedded help: background and applications for
technical communicators. Technical Communication 48(1):105-115.

(Just a side note: This is one of those useless so-called theoretical
articles published by STC that no real practitioner would ever want to read.
Unless they wanted to produce a useful help system, that is. <g>)

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."--Kim Roper

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
Save $600: Create great-looking Help files and software demos with
RoboHelp Deluxe. Get RoboHelp and RoboDemo - our new demo software - for one
low price. OR Save $100 on RoboHelp Office in June with our mail-in rebate.
Go to
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: White papers?
Next by Author: Focus out?
Previous by Thread: Mostly fixed RE: Word Table Shading Messed Up in PDF
Next by Thread: Apology

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

Sponsored Ads