Re: On-line help questions

["Susan W. Gallagher" <sgallagher -at- STARBASECORP -dot- COM>]

Joyce Genser replies to Rosie...

> Rosie Wilcox's advice was:
> >"Don't let the developers push you around and tell you it will be >easy to
> tie in your context-sensitive help, so "don't worry about it >until one day
> before the program is due"!"

> This sounds like excellent advice. Does anyone have any advice to counter a
> programmer who tells you this? How can you get a programmer with this
> attitude to cooperate? I am on my first on-line help project with
> context-sensitive help and it is the LAST thing the programmers want to deal
> with.

First of all, whether the context sensitive help is difficult
to hook into the program or not depends greatly on the programming
language. Not all languages do things the same way. For example,
Microsoft Visual C++ comes with a handy utility that generates
help IDs for all dialog boxes and menu items. Once these IDs are
at hand, all you have to do is use them as your topic IDs,
then put the help file and the program in a dark area of the
network for a few nanoseconds while voodoo happens and you're
done.

Smalltalk, OTOH, requires the programmer to input a topic ID
into the initialize statement for each window you draw and an
array of IDs for each menu on the menu bar. Not particularly
difficult, but time consuming and error prone. During the
last few weeks of a *major* project written in Smalltalk, we
found out the the original system programmer had placed a
small integer limit on help ID numbers so none of my carefully
designed number categories above 32768 (or whatever it is)
worked at all! %-)

And I've heard some real nightmare stories about programs
written in database languages. Not the kind of problems I
wanna hafta face at all!

So... Advice number one... Don't panic yet. Find out what
you're up against first.

Advice number two... Make it perfectly clear that CSHelp is
as much a part of the program as any other snipett of code
and is just as needy of (and worthy of) a good going over
by your QA department. They're gonna need plenty of time
to...
   * press F1 (or whatever) on every dialog box to
     make sure the correct topic comes up
   * click the Help button on every dialog box to
     make sure the correct topic comes up
   * check each internal jump to make sure the
     correct topic comes up
   * check each topic for placement in the correct
     window, proper browse sequence, and so on

Any product manager who thinks he can get away with any less
probably won't be a product manager for long. (And I know
that's small consolation while you're crouched in the
trenches!)

How do you get the programmers to cooperate? I dunno,
sometimes food helps ;-) but mostly you need to be
persistent.

Find out what you need for topic IDs, whether they'll
be generated by the programmer, whether you need to
make them up, or whether the programmer will. Tell 'em
you need to know *now* because in any help authoring
tool it's really time consuming and error prone to
change 'em later (they're what all you're jumps are
based on too).

In your doc plan or project schedule, include time for
QA as well as technical review and editing. Management
buy-in would be nice at this point %-) so emphasize
product quality and marketability.

Good luck!

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