Re: Summary-Planning Online Help

["Joyce K. Genser" <JKGenser -at- AOL -dot- COM>]

Thank you to everyone who sent suggestions for "Planning an Online Help
Project". The response was even better than I had hoped. In case you are
planning an online help project, here is a condensed list of suggestions.

WINHLP List
Several people suggested subscribing to the WINHLP-L (Windows Help Compiler
Discussion List). I did subscribe and I am happy to have found another
resource of industry information. If you would like to subscribe to the list,
type the message:

SUBSCRIBE WINHLP-L type your name

then send it to:

LISTSERV -at- ADMIN -dot- HUMBERC -dot- ON -dot- CA

Books
"Developing Online Help for Windows" by Scott Bogan, Dave Farkas, and Jon
Welinske, published by SAM,  ISBN 0-672-302239-6. This is an excellant book.
It covers the basics such as defining topics and coding WinHelp files.
I tried to find another copy, but the publisher is out of stock and they no
longer
have the rights to the book. So, if you find a copy grab it! (If the authors
read this summary, please, please republish this book.)

Another well written book is "The Developer's Guide to WINHELP.EXE,
Harnessing the Windows Help Engine" by Jim Mischel, published by John Wiley
and Sons, ISBN 0-471-30326-7. This book has a more technical orientation than
the book above, but it is also invaluable when writing Windows help.

Magazine
There is a magazine called WinHelp. I have not seen a copy, because the
authors will only take a years subscription, they will not send individaual
copies for review. If you are interested you can contact WinWriters at:
800-838-8999 or 206-285-2605

Speak early and often with the programmer(s).

In the Help text, tell the user:
* where the they can go from the screen they are on.
* what the different fields mean.
* what process they can access from the screen.

Design of the Help system:
* Place each procedure into a single help topic.

* Plan the context strings and context ID schemes before you start writing.

* For each help panel, write a brief description of each screen on a
stickey-note. Stick the notes to a blackboard, and draw arrows between
associated screens showing the direction of the information flow. When you
are done, copy the link information to a card file or database. (Note:
Although this method of planning sounds good in theory, my project was too
large to accommodate this system. I found Lotus 1-2-3 made the screen panels
and information flows more manageable. My spreadsheet covered 16 printed
pages but all the pages were easy to work with. Lotus kept track of all of my
screens and relationships.)

*  Use an index card for each section of the screen that was going to have
context-sensitive help. List the screen 's name, file location, any jumps and
pop-ups.

* Use the Forehelp authoring tool to diagram topics, links, and jumps. (Note:
This is a suggestion I am using along with the LOTUS 1-2-3 diagram. Forehelp
has three different ways to show a diagram and I don't have to compile to see
what the screen will look like.)

Writing the Help Text:

* Use the language of the most experienced user.

* For novices, use pop-ups for basic definitions, termonology, acronyms, etc.

* Basic indusrty concepts are another good way to use pop-ups.

* Create an index of all the procedures in the WinHlp main window.

* Use secondary windows as a jump from the main topics in the main window to
show individual procedures.

* Add synonym entries for less experienced users.

* On the secondary window, place buttons to print the procedures by copying
the procedure text to the clipboard and closing the secondary window.

* Break the product down int tasks, group similiar or related tasks, organize
them into chapters and sub headings, and use the local table of contents ( a
mini table of contents of each section), as a means of getting to the lowest
level of information.

Thank you again for your very helpful advice.

Joyce K. Genser
Sr. Techncial Writer, New York