I have to agree with Mike in that writing help files is akin to
doing the dishes or washing the car! It's a necessary evil however and
there are a number of things one can do to make the job a little less of a
pain in the arse.
For example, one can be very strict about commenting their source
code and then later use these comments to help remember salient points they
might otherwise have forgotten. Me, I keep a working journal. It's part of
a utility application I built for myself which first and foremost allows me
to add a new project by name and version and then at the end of the day it
scans my project and other named directories and/or specified files,
creating a database record of my project. It's a poor man's version and
source control utility. And for each new record of the project it allows me
to add an unlimited amount of text which I use to notate exactly what I did
in that particular record and what I intend doing next. Along with notes
such as these I also add comments about use and if it is meeting my design
goals or not, as well as information I think is important to get across to
the user when I write my help file.
In any case, and no matter how you do it, I believe one of the most
important things about writing help files is that you keep good notes while
writing the program, because you can never remember every point you need to
make when you finally reach the time for writing one!
Second but just as important...lay out a structure for your help
file and then stick to it! One of my pet peeves is help files that read
like a cheap magazine, having you move from page to page just to read a
small article! Links are great but sometimes help file writers depend way
too much on them! Take a look at a well structured help file...one that you
think makes it easy for you to scan thru as well as finding what you need to
know when you need it! There's no copyright on how they are structured so
feel free to borrow from the best and then make an outline of the help file
that will lead the first time user from the point of installation on onward,
taking and explaining along the way each step in the program's use just as
you want the user to actually use it. This gives you more control and
provides the user with a sense of direction. The structure I use is
pretty common. I usually have three main topics in my help files...the
first being an introduction to the application which provides in a series of
short sections what the application does, it's history if relevant, it's
installation, copyright and legalities, and last a developer contact
section.
The second topic is a series of individual steps, one per page
carefully entitled so the user can more easily find the section wanted at
the moment, and which is in essence a walk-thru of the application's general
use. And I try to write this section using the same steps and in the same
order I designed the application to be used in. It's this section where
detailed descriptions and/or explanations are given, and where I add links
to each physical command from. Admittedly, this is the most difficult part
of writing a help file and where I spend the majority of my time while
writing it!
The last section is the one where I add my lists of commands,
possible errors or problem troubleshooting, and any technical references are
made. This section is not written to be read in the usual manner but is
provided as a series of information bits which I link to from the second
section as a reference only!
Finally, don't allow the task of writing a help file become
overwhelming! By keeping notes you'll get a handle on it early, and then
when you finally do sit down to write it, do so in small pieces...that is as
a series of encapsulating topics...one per point you wish to get across. If
you're already a decent writer then you'll have no problem and can do so in
any free-form style you like, but if not, then write it as a series of
short, easy to read and understand topics that say ONLY the important facts.
For example, I have a habit of being over-verbose, ( as you can tell from my
message here. <g> ), so I can easily write a page or two about a single
button click! But no one wants to spend his whole day reading about a
button click so I've learned to simply provide a list of commands and the
various actions the user can take to initiate them. I state what the
command does, what controls initiate it are called, where they can be found,
and what happens when the command is given. That's it! Then I break this
command list down into relevant sections, but still keep them all together
in a "Commands" topic, linking to each one from where ever else in the help
file their use might come up!
Anyway, I hope this is of some help to you. Just remember we all
have to do it!
from Robert Meek dba Tangentals Design
__________________________________________________
Delphi-Talk mailing list -> [email protected]
http://www.elists.org/mailman/listinfo/delphi-talk
