TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
original message (cropped):
"I've been approached by the Software Manager to configure a help system; as
he says, "...it'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?)"
response:
Chris,
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
involved.
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
