Re: On-line help questions

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

Amanda Taylor writes...
[snip]

> 1.   Does anyone have any software recommendations for Windows Help?
>      RoboHelp? Doc-to-Help? Forehelp? I'm working on a PowerMac 7100.

The three tools you mentioned are all good and all have their
uses. Save Doc-to-Help for when you're trying to single-source
paper and online documentation.

Use RoboHelp if you'll be lost without the editing capabilities
of Word, if you want to learn about the structure of online
help documents, if you want to take shortcuts in editing
repeptitive elements, and if you're looking for an easy way
to link in context sensitive panels.

Use ForeHelp if you're not looking for wizzbang editing (it
has limited style capabilities, cut 'n' paste, limited search
and replace, etc.), if you want to be shielded from the document
structure, if you'd rather do things the easy way than the quick
way.

> 2.   Does anyone know of any seminars/classes that would be helpful
>      for learning on-line help software and/or the basics of writing
>      on-line help?

I have no recommendations here.

> 3.   How about any books that will help me with the basics of writing
>      on-line help?

William Horton's book for theory. Otherwise Idunno about books.

Subscribe to the Winhelp Journal for ongoing articles about
creating Windows help.

Subscribe to the Winhelp-l list on the internet for help
specific conversations.

Mostly, books will give you support but doing it will build your
confidence.

Shameless plug ahead ;-)
Contact Liz Smith at the SD Supercomputer Center (this year's
STC Newsletter Editor) for a reprint of the article I published
in March on organizing and planning for Windows help.
End of shameless plug ;-)

> 4.   Are there any *Supreme* "Do's and Don't's" that I should be aware
>      of when writing on-line help?

Answer only one question per topic. If the information you
have doesn't relate to the question being answered, put it
elsewhere.

Be clear and concise. Don't get wordy. And keep topics as
short as possible.

Use simple formatting. Avoid italics like the plague. Indent
in tenths of inches rather than quarters or halfs. Reduce
line spacing between paragraphs, too. White space is whiter
online.

Limit your use of color in text -- it can be distracting.
And using colored text usually leads to the urge to hard
code background and text colors. Bad idea -- users
(rightfully) prefer to control their own environment.

Using colored icons OTOH to mark information (like a
dialog box for context sensitive stuff, something
else for procedural topics) helps the user identify
the kind of information presented.

Avoid the urge to link everything to everything else. Keep
the link path clear and logical. Let the users arrive at a
point where they know they've seen all the information on
a subject.

Keep hyperlinks all in one place rather than sprinkling them
throughout the text (e.g. at the end of a topic in a 'see
also' section or as a popup from a button on the non-scrolling
region). This encourages the reader to finish the whole topic
before jumping off into hyperspace.

Resist the urge to create long topics of conceptual info.
They're a waste of disk space. Nobody will read them.

One last bit of advice -- use online help. Access the help
file for all of the programs you use. Notice what information
*you* are looking for and whether you found your answer or not.
Your best tutor will be the critic in you.

Hope this helps. Feel free to contact me off-list if you
have any specific questions.

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