Survey Summary--Help Authoring Tool Research

[Genevieve Burt <gb_techwriter -at- yahoo -dot- com>]

Thanks to all of you who responded!  

I?ve broken down the survey responses into 3
categories:  Stats on what Help Authoring Tools (HATs)
you?re using, Words of Wisdom, and How does your help
get integrated with your software.  

Read on to see the survey results...

==Stats on what HATs you are using==
Of the people who responded to my survey, 

14 use some version of RoboHelp.  

5 use Quadralay WebWorks in conjunction with
FrameMaker to create HTML help, HTML and JavaHelp.

1 uses Doc-to-Help to create user guides and online
help at the same time, starting the documentation in
Word.

1 uses ForeHelp + FrameMaker.

1 uses AuthorIt to convert Word docs to WinHelp.

1 uses HDK to create context-sensitive help, task
help, merged help systems architecture, HTML browsable
books with embedded TOC, and HTML help.

1 uses FrontPage to create WinHelp.

==Words of Wisdom==
Here are some of the Help Authoring tips you gave me
(some of you gave similar advice, so I didn?t list it
all):

?Don?t forget the planning process?which takes more
time that the writing phase!?

?We believe that help needs a much more rigorous
process than writing manuals.  We have a process for
each topic.  These parallel-processed steps are:
--set up files
--set up topics
--research
--write
--QA self-check
--peer edit
--tech edit
--enter peer edit
--enter tech edit
--create graphics
--edit graphics
--tech review graphics
--import graphics
--complete all follow-ups
--set up internal linking
--test links
--set up context-sensitive linking
--test CS links
--Index
--TOC
--proof on paper
--proof online
--enter corrections
--link follow-up
--send to testing

?The most important part of an online help system is
the index?that?s sometimes the only way your readers
can find out what?s in there and get to what they?re
looking for.?

?Push (and keep pushing) to get a testing process in
place to verify the accuracy and functionality of the
help system.  It should be tested along with the
software functionality as part of your company?s
software development process.?

?We single-source, but we don?t work backwards by
creating one material for one medium and then forcing
it to work in another medium.  The tool you use is
unimportant, as it depends on your project
objectives.?

?It?s better to write a manual that looks like a help
file than a help file that looks like a manual.  Only
user guides are really helpful in WinHelp format. 
Think in terms of bite-sized topics and topic
relationships.  And the earlier you start writing the
help, the more help it is:  it?ll give you and the
developers an early crack at improvements to the
application.?

?I learned a LOT about help authoring from Jared
Spool.  If you are ever at a conference and can see
this guy, definitely do so.  His web site is
www.uie.com.

?Start out simple.  Build in the bells and whistles
when you?re comfortable with the tools.  Don?t try to
do everything the first time, because a lot of your
time will be spent on the learning curve and ironing
out the problems.  After you do choose a tool, find
and use a listserve or user group community that can
help answer questions.?

?Get involved early in the development process and be
a user advocate.  Test and re-test your links. 
Realize your help file is likely to look differently 
on different PCs, based on the way you collected your
graphics.  Realize that graphics inflate the size of
your help file greatly?decide whether you actually
want them.?

?Whatever you choose, you?ll be fine.  And if you
aren?t, just pick another tool.  I?m from the school
of thought that it doesn?t matter what tools you don?t
know, you can always learn those?I?d rather have
someone who knows how to write.?

?Be to the point and concise.  Writing help takes a
completely different POV from writing hardcopy user
manuals.?


==How does your help get integrated into your
software?==
Here?s how you explained it:

##RoboHelp implementation comments were:
?RoboHelp generates IDs which the programmer links to
objects.?

?I send the .hlp and .cnt files to the programmer, who
integrates it into the apps.?

?Our developers create a help ID for each field, menu
item, button, etc. as they are setting up the GUI.  We
wrote a tool called ?CFSHelpFix? that we run against
the compiled code to resequence the numbering in each
load module in the application, and then they generate
a master .hh file.  We import the master file into
RoboHelp and connect the help IDs to the appropriate
topics.  In some cases, we want a specific display
based on the data currently being processed so they
write an external action block where the data is
mapped to a variable that calls the help ID from a
data table.?

?We provide the API calls to the programmers.?

?To create WinHelp, either you or the developer must
prepare a header file (filename.h) which is a text
file with a list of the help topics.  Each topic has a
name and number.  You put the topic name into the
footer for the topic with a # sign so the system
understands what it is.  The developer puts a note in
the program that tells the system that if somebody
opens to give a dialogue box and presses F1 or a help
button, the particular help topic opens.?

?Our programmer takes care of integration.?

?I give the programmers the context ID for a screen
and they program it in.  I have worked in places where
the programmers gave me the IDs.?

?Our Programmers write the code so that a specific
help topic (URL) is called upon when clicking help on
each window with context-sensitive help.?

?Our developers just provide us with the map IDs for
each programming window.  They do the rest of the
coding.  We just write the content, compile, and then
hand them our .hlp files when the executable is
compiled.? 

?Our programmer puts a call in.  We?re not doing
context-sensitive help yet.?

##Quadralay WebWorks comments were:
?I provide the software engineer with the HTML file
names.?

?I provide the help to the engineer, who places it in
the correct position.  The software calls are already
there.?

##Front Page comments were:
?For What?s This? Help, we assign numbers to all of
the context IDs and deliver a .BAS or .H file to the
developers, who then map their controls with them.?

##ForeHelp comments were:
?We provide help files and context #s (where nec.) to
the programmers.?

##Author-It comments were:
?We deliver help to the developers with a map of
topics to forms (for context sensitivity.)  Then we
pray.  Then we see the final result and try to help
?em fix it.  It?s not a smooth process (yet).?

##Doc-to-Help comments were:
?We use context-sensitive ID numbers to manipulate
based on topics.  I work with a programmer to come up
with numbers that will match the software app., so
that when we do a build, all the numbers correspond. 
That way, when you invoke help from the software, the
correct help actually appears.?

==Raw Data Available==
As part of my research process, I?ve created a table
that compares the durrent (January 2000) prices and
features of six HATs:  MS HTML Help Workshop,
AuthorIt, ForeHelp, RoboHelp, Doc-to-Help, HDK, and
WebWorks Publisher.  I?ve also created a table that
compares  each survey response I received, breaking
each response down according to people per project,
project size, project type, tool choice, and type of
help created.  If anyone would like a copy, please
e-mail me at this address:  genb -at- bachelorcontrols -dot- com -dot- 
 The files are in MS Word97 format.==

==My Decision==
I'm still testing the demos, but based on my research,
my choice is now between AuthorIt and RoboHelp.  Why? 
AuthorIt because:  AuthorIt's interface is easy to
use, their help files are wonderful, and their free
tutorial has quickly given me the basics I need to
start creating help.  RoboHelp because: since it's
what most of you are using, help should be easier to
come by if I need it.  


Thanks again, Techwhirlers, for your help!
--Genevieve



=====
""""""""""""""""""""""""
Genevieve W. Burt
{Technical Writer}
Bachelor Controls, Inc.
www.bachelorcontrols.com
""""""""""""""""""""""""
__________________________________________________
Do You Yahoo!?
Talk to your friends online with Yahoo! Messenger.
http://im.yahoo.com