Re: Context-sensitive Help

[RoseCrowe <ncrowe -at- PRIMENET -dot- COM>]

On Tue, 31 Jan 1995, Susan Gallagher wrote:

> 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).

I have forwarded this suggested to our developers.  However, our
applications are designed to match long data-intensive forms.  It's
not a very pretty design, but it's what our users wanted.  This means
that we have quite a few things to document besides dialog box
controls.  We may have to divide the help into enterable fields and
displayed fields or something.  Also the "forms" are divided into
sections that are not strictly left-to-right and up-to-down and
are not labeled.

> 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.

No.  Yes.  Our shop is involved in Rapid Application Development.
The developers think our slow response is messing up the
team's as a whole response time to the users.  (In RAD, developers
create applications, show them to the users, change them based on
user input, and then repeat the process.)  I have made it
clear there will always be a lag time, no matter which design
we use.

[snip interesting stuff about win95]

> 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.

OK, good word taken.  You helped me back down, but I still
have a design problem!

> 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.

Most of our products don't have a main window, but are a series
of windows.

>Then go for a simpler design
> for the context-sensitive stuff. Include a brief description
> of the dialog's funcionality and then describe each control.

Sigh.  I wish it was that simple...


> 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.

Thanks, Sue.  This week I worked on making peace.  I can't help
but worry about the tendency in this organization to let developers
dictate help design (I will resist that), but I won't resist
coming up design alternatives as a whole team.  This incident was
a good learning tool for our developers, who attempted to provide
a simplitist solution to our help design problem.  They ended up
learning that documentation design is not that simple.  What we
do in the help affects our manuals as well and what we do in
one application affects another application.

Thanks to all who replied,
Rosie (NorthCrowe)
ncrowe -at- primenet -dot- com
rwilc -at- fast -dot- dot -dot- state -dot- az -dot- us
*******
"Half an hour's meditation is essential except
when you are very busy.  Then a full hour is needed."
-St. Francis De Sales