Re: Context-sensitive Help

[Susan Gallagher <75462 -dot- 3613 -at- COMPUSERVE -dot- COM>]

RoseCrow writes:
**************included**************
We are involved in a bit of a controversy here and I would
appreciate all input.
We are creating help for a Windows application being developed
with PowerBuilder.  We are writing the help using Robohelp.  The
help files include How Tos (not tied into context sensitive help)
and help on the menus and windows in the program (tied into context
sensitive help).  The menu/window level help shows a picture of
the application menu or window.  On the window pictures, the user
can get field-level help in popups.
**************end included*************************

This is is a technique that became very popular a year or so ago.
Most help files now are simply listing the dialog box controls
and a brief description (see Word6 for an example).

**************included**************
Our developers feel that our help systems are lagging in delivery
behind their applications.  They believe that the time it takes
to recapture the windows pictures and tie in the field topics
is what makes us unable to complete the help system at the same
time they complete the application.
**************end included*************************

Does the concept of UI freeze mean anything to them? Or is
this the kind of shop that keeps on adding features until
midnite the day before golden master???  Doc staff needs
to make it clear to programming staff that it will take
(insert best guess here) between the time development
freezes the UI and the time the docs and help are ready
for the QA people to start banging on.

**************included**************
Their solution is to write field-level help and tie that in.
We tech writers do not believe that this will solve the problem.
We believe there will still be a lag time.  We think that the
lag time will decrease as the product stabilizes.  We also
do not think that the users will find field level help "helpful"
without windows-level help.  We think the developers want us
to write database descriptions of the fields on the screen,
rather than supplying true process help.  (BTW, you can jump
from the window level to the how to topics related to that window.)
Our help design was user-approved and developers also approved
it before we started writing.
**************end included*************************

What they're asking you to do very closely resembles the
context-sensitive "what is it" help for Win95. The only
problem with it is that users will not be able to access the
help file. In Win95, users will get pop-up field level help
for each dialog box control. A help button (if one is deemed
necessary) will connect to conceptual help for the dialog.

**************included**************
There are a bunch of political issues surrounding this, but I
would mostly like feedback about field-level help vs. window-
level help and the use of graphics in help files.  We are
willing to change our design, but we are not getting what
we consider a good alternative from the developers.
Do you have any suggestions?  Have you found field-level
help helpful to the users?  Are there materials out there
about Help design that will enlighten us as to what
users really want?  Are there alternative solutions to
helping us keep up with the developers that we may propose?
Thanks in advance!
**************end included*************************

Sounds like you've got two armed camps there, and I don't
envy your situation! But don't hold on too hard to those
complex shed files. They'll be old-hat before you know it.
Companies are aware of the extra disk space they consume,
and so are users.

Try just providing your window reproduction for the product's
main window. This will get your users up and running without
breaking the bank on disk space. Then go for a simpler design
for the context-sensitive stuff. Include a brief description
of the dialog's functionality and then describe each control.

Most importantly, try to make peace with development. Explain
to them the importance of giving you time to catch up with the
product. If they can provide you with advance information on
a dialog's controls and functionality, so much the better, but
let them know that quality docs take time (whether paper or
online). If you guarantee online help xxxx days/weeks after
completion of the UI ***and stick with it***, that should go
a long way toward mending the fracture between doc and dev.

Good Luck! Let us all know how it goes.

Sue Gallagher
StarBase Corp, Irvine CA
sgallagher -at- starbasecorp -dot- com