How to evaluate help authoring software?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Rosemary Horner reports: <<I've been given permission to research outside
software for [help authoring]... The problem is, I have no idea what to look
for... I've looked at the websites for various different authoring tools:
RoboHelp, Doc-to-Help, AuthorIT, SevenSteps, MS HTMLHelp, HyperText Studio,
DotCHM, HelpBreeze... And I've searched the archives here and at HATT. But I
feel like I don't know enough about the terminology involved and the use of
these types of tools to be able to evaluate them.>>

If you're really just getting started, I have two strong pieces of advice
before you even think of choosing a tool: First, take a basic course in help
authoring, or at least read a good book. (I'm quite impressed with the stuff
done by Mary Deaton and Cheryl Lockett-Zubak; their Win 95 book is almost
certainly long out of print, but I'd be surprised if they haven't updated
it.) Second, make a list of the concepts or terms you don't understand and
bring them here in search of enlightenment; you'll find it.

In terms of actually evaluating the software, most of the biggies offer free
demos of their software, whether on CD or downloaded from the net. Install
these demos and start playing with them. I'm a minimalist when it comes to
online help, and thus, believe that any of the major packages provides a
truckload of tools that let you create a decent help system. But all the
current releases have tons of bells and whistles that you'll never need--or
that help users will never use. So don't compare solely on the basis of
feature lists. Since all the main software can do the job, it becomes more
important that you like the way the software works.

In my opinion, good help software must let you perform the following tasks
quickly and easily:
- create a new topic (set up the file or section of a file that contains the
text, and let you enter and format the text efficiently)
- set the topic's properties, including the efficient creation of a good set
of index keywords
- create hyperlinks between _and within_ topics
- compile and test the help file (ideally without leaving the authoring
environment)
- provide debugging assistance when the compiler encounters an error

You'll be spending 95% or more of your time doing these things when you
write a help file, so these are the parts of the software that must work
flawlessly and (equally importantly) that must work the way you do so you
can work productively. If you can't abide mousing around, there must be
easy-to-use keyboard shortcuts for all the main features; if you want to
work in Word or Frame, the software must work well with Word or Frame; and
so on. You may also have specific needs for your own work environment; make
a list of these too and test how well the software meets these needs.

<<Our current help system allows the user to... open the help viewer window
with the help for that page and navigation for that app displayed. There's a
search button in the help viewer window that allows you to search for a term
across all our apps or in a specific one, or to view all help for a specific
app. All the apps that have help are listed. Is this an uncommon feature or
likely to be an issue?>>

This should be easy to do in any help software. And for the record, it
sounds like a nice, user-friendly design.

<<I think all our development is done in asp.net.>>

Find out what software the developers are actually using. Although this
knowledge isn't essential for creating the help files themselves, it's very
useful for knowing how to create map files so the developers can make the
help context-sensitive (different programming environments have different
requirements). It's also perhaps a useful tool in troubleshooting.

<<And I only need to be able to create online help, not printed manuals.>>

Even if that's the case, it's likely that at some point you'll need to do
both print and online information. Thus, make sure your solution lets you
swap information easily between print and online documents. Sometimes copy
and paste is all you need; sometimes you may want to investigate a true
"single sourcing" solution.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada 
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."--Kim Roper

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by May 15. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.