RE: Context-sensitive help - HTML help and VB application

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

Hi Dave,

We're in agreement. Here are ideas on how I've learned to take control and
make helpful help which went against Microsoft's (previous) role model's of
"pop-up happy", "annoying Mr. Paperclip", and "circular references, limited
browsing, and limited TOC".


===================== Context-Sensitive Help

I've done what you suggested in the past regarding pop-up's. That is, I've
had hyperlinks in my pop-up's that took the users to a main topic. Through
experience I've discovered that even this is less than ideal.

===================== going further off of Alyssa's topic

The first problem is that it still takes the users three clicks to get to
useful, browsable, scrollable information: (first click) question mark in
the dialog box; (second click) field in the dialog box to a pop-up; (third
click) hyperlink from within pop-up to a banner topic. Three clicks as
compared to one click -- on the help button.

The second problem is worse from a documentation perspective: duplicate
information. Because of the nature of pop-up formatting, you can't automate
the re-use of text.

For example, say that I have a dialog box with n-fields requiring n
pop-up's. I might decide that it would be very beneficial to the user to
give each pop-up a link to a main topic that discusses the entire dialog box
so that they don't have to click 2n to get all of the information.
(Actually, it is 3n if you count the click that makes the pop-up go away.] I
have two choices. Either my main topic repeats all of the real meat for my
pop-up's; or, my main topic implements pop-up jumps as well. The former has
maintainability problems, the latter is lots of flash and only reduces the
clicks to n.

The third problem, if my pop-up's really do have some meat to them, [1] you
can't copy-and-paste from them, [2] you can't browse forward-and-backward
from them (when they are displayed as pop-up's), [3] they look ugly if
displayed as main topics should you assign keywords or browse sequences to
them...

==================== Alyssa might be able to use some of this

Sooooo, the hard-line position that I've started to take with development
is:

[1] They should continue to assign context ID's to as much of user interface
as they want, to each and every little field and checkbox... I don't care.

[2] Instead of them making API calls that start a pop-up, I make them change
it to be a call to a banner topic. (In other words, there are no pop-up's
from the program.) This fits in well with the HTML world.

[3] If they can find a way, I'd even have them route the question mark that
normally starts context-sensitive help (e.g. "What's This?" help) to be a
normal help call to a banner topic -- the same topic a help button would
display.

[4] If I can get them to do it, I make them create a "help" button within
each and every dialog box even if there is that dinky little "What's This?"
question mark sitting right next to the dialog box close icon. (Nothing says
"help" like a button labeled "help.")

Then I do whatever I like. Usually, I create one or two topics that
completely explain the dialog box.

What do I do with all of those context ID's? Either I place them at
strategic points **within** the topic or right at the beginning of the
topic. It is also possible to alias all of those context ID's to a single ID
in the project file. I don't like this method, because it doesn't make the
topic (e.g., RTF file) re-usable in other projects without having to
maintain long, strange, programmer-cryptic lists of context ID's in multiple
HPJ files. (This was a major problem I had to solve at my last job; we were
re-using RTF files that contained common information yet the
context-sensitivity worked in one help system and not another.) It is better
to plaster a whole bunch of context ID's somewhere in the topic (and owning
RTF file) and then forget about them. If the developer changes names, I add
the new names and don't bother deleting the old (CYA, just-in-case, backward
compatibility, and it doesn't hurt).

Because it's a banner topic, it can be scrolled and browsed. If I placed the
context ID's inside the topic (and not just at the beginning), I can have
other links from other places (even the CNT) to exactly where the user needs
to be.

If the developers create context ID's and use API calls for banner topics,
it gives me more control. If I really want to have a pop-up, I can route the
banner topic to a pop-up and not display the main window using macros. (I
couldn't do this from pop-up's; I tried.)

I'm also partial to putting screen-shots of the dialog box that I'm
explaining within the topic. It may be redundant for context-sensitive
jumps, but the annoyance of having to scroll past an image is more than
offset by the warm-fuzzy-feeling that the users get in having confirmation
that the topic really does relate to what they're seeing on the screen.

Actually, if I am smart about my in-topic-jumps, they don't even have to
scroll past an image; the jump does that for them. If they are confused
about where they are, scrolling up shows the image and provides the needed
validation. Moreover, the image validation is especially important for entry
to the topic from other sources -- namely, the TOC and index. If they want
to do something and my text explains it, the image provides the necessary
clues as to what to look for in the program itself.

================ Summary

The point of all of this is that **I** take back control of the help file. I
have the programmers give me that control by making sure that context ID's
are assigned and that the proper API calls are made. No more stinkin'
pop-up's unless I say so -- like for definitions.

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com


> -----Original Message-----
> From: david -dot- locke -at- amd -dot- com [mailto:david -dot- locke -at- amd -dot- com]
> Sent: Friday, April 06, 2001 8:36 AM
> To: glenn -dot- maxey -at- voyanttech -dot- com
> Subject: Context-sensitive (TECHWR-L)
>
>
> Glenn,
>
> If you are doing WinHelp, you can use a popup in What's This Help
> to link, a single link, into the body of your help system. I put a
> link in the popup.
>
> Then, I jump to a More topic that expands the popup entry and contains a
> list of links to feature, need, and task topics. You can only use
> one link, because the secondary window closes after the jump.
> Putting the root of a tree in the secondary window would cause the
> user to open the same popup over and over again to go to different
> branches. There is no WIN Help complier problem with having links
> in the content of a WTH topic.
> The use of WTH and no links came about, because incorrectly informed
people
> evangelized this. There is no technical impediment to doing it the way I
described.
>
> In addition, if you use a shortcut menu to invoke WTH you can do
> so for any > number of facet's involved. You can have an option for What's
> This, How Do I Use This, What Do I Need To Know To Use This, What's
Related To This.
>
> Once we get to HTML Help, this metric--no jumps--was embedded in the
> functionality. But, if you get your programmers to write some
> code, they can invoke the main window, instead of the ASCII-only
> secondary windows. The problem is solvable.
>
> The main problem is having people like Jarod Spool going around
> saying that nobody reads the help. This misses the point. Nobody reads the
> help, because in the past they learned that it wasn't helpful.
> It is up to us to ensure that help is always helpful. Then, users will
read it.
>
> I have always used context-sensitivity as an index into the larger help.
>
> Have a great day.
>
> David
>
>


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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, 
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline 
April 27. http://www.pdfconference.com. 

---
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 
http://www.raycomm.com/techwhirl/ for more resources and info.