RE: online help system...HELP!

Subject: RE: online help system...HELP!
From: Ian Ferguson <IanFe -at- Attachmate -dot- com>
To: 'TECHWR-L' <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 3 Oct 2000 11:38:48 -0700

original message (cropped):
"I've been approached by the Software Manager to configure a help system; as

he says, "'s time to stop talking about it..."

My qualifications include limited knowledge of the programming language that

the system is written (C++) and above average HTML skills. I started writing

for this company 3 months ago and have never written online help.

The software that I document is extremely layered (real-time and off-line
analysis for atomic force microscopy). I'm still learning this system, but
am up for the challenge.

Sooo, my question is this, where do I begin? The software is going through
such a drastic gui change right now, and I'd like to write the help system
as the engineers write the new system. (Can this be done?)"


I work with HTML-based help systems, and really enjoy two things about them:
HTML always does what I expect (Word seems to have a mind of it's own), and
there's no compilation process. I change the source, and it's done. There
are two things I don't enjoy about these systems: browser incompatibilities
and the Java applet we use for navigation. It's frustrating to come up with
a nice CSS solution and have it appear different in Netscape. The fix is
always less graceful. The Java applet table of contents we use tends to have
issues with certain browsers only when used over a network and only when
used in conjunction with a certain javascript, etc. There's a lot of testing

There isn't an easy way to print these help systems. We're working on a way
to get the content into PDF for printing. Otherwise, though, HTML is easy to
learn, and easy to work with. If you make a whole system with it, be sure
that your code is consistent, so that when things change, you can make
changes globally. Also, converting to XML will be easier.

For context-sensitive help, linking directly from your app to you help
system, don't use your filenames in the app's code. Have an intermediary
file with the name of the button pointing to the help file. That way, if you
change the path or filename, you don't have to bother the developers.

About writing the help system as the engineers write the new system, I'd say
that describes how I work all the time. Changes happen constantly. I'd begin
by making a high level overview of a structure for your system. Define
sections such as getting started, microscoping atomic forces, reference
guides, etc. Make some template HTML pages (here's an overview topic, here's
a procedural topic). Put in some content and a navigation system, and start
testing. Test on the systems your users will be using. Make sure to try
different browsers and monitor sizes (and resolutions) if that makes sense
for you audience. Then add content and do some user testing to make sure
your help is helpful.

I think there may be books about the process of designing a help system.

Ian Ferguson
Technical Writer, Attachmate Corp.
ianfe -at- attachmate -dot- com

Previous by Author: node vs. element
Next by Author: Part-time tech writing
Previous by Thread: Online help system...HELP!
Next by Thread: online help system...HELP addition

What this post helpful? Share it with friends and colleagues:

Sponsored Ads