Writing help files

I strongly believe that including a help files is a mandatory requirement to any software - be it for a simple, complex, trial or a full version of the software.  You may wonder, why for a trial version? My answer would be that a user is more likely to buy the full version if they actually understand how your software works!

You can present your help file in a number of different ways - the way you select depends on the type of your product (and also, how lazy you are feeling…)  Here are some options you have:

1. A simple text document
2. Help window within the software (no separate documentation)
3. HTML help file read through the customers HTML browser
4. A help file which is read through a dedicated help file reader on the customers machine
5. A link to help file on the internet

Each of the above have their own advantages and disadvantages.  Consider the following…

• Options 1 and 2 are suitable if you have a simple, self explanatory software. If going for option 1, keep things short and use clear headings. A disadvantage is that links and media files will have to be left out.  Formatting of the text may also suffer.
• With option 1, you should output files in a .txt format or if you want formatting, in the .rtf format - this is to ensure that all computers can read the file without installing additional software.
• Option 3 is self explanatory. It can be as detailed as you need with links, media and formatting. A customer doesn’t have to be connected to the internet because it is installed locally onto the machine.  You however have to  have  a basic understanding of how to produce webpages.
• Option 4 - what do I mean by a ‘dedicated help file reader’?  well, basically this is a software that is installed by default onto most modern PCs which has the sole purpose of displaying help files.  The advantage of this method is that files can be as rich as a webpage, be properly displayed (like a book) and is installed locally as a single file (so its easier for you to manage).  We will look later at how to produce such a help file.
• Option 5 is great if you need to keep updating the help file… especially as you may not be sure in the early stages! Unfortunately, your customer will need to be connected to the internet to access this.

The content of the help file is entirely dependent on the application itself but here are some important areas to focus on:

1. Introduction to the application – what is its purpose? What are its features (without going into too much detail)
2. Systems requirements page
3. A getting started page which outlines the steps to carrying out simple or common tasks
4. Page listing the full features and links to detailed exploration of the specific features
5. Frequently asked question. Try and think of what may be common questions (e.g. I’ve lost my password! What now?)
6. Possible errors and solutions
7. How to install/uninstalling
8. Links to your website and online help resources and your contact details
9. Licensing information

I would highly recommend:

See how other people have done there help file by downloading similar applications.

The information above should be enough to produce a help text file for a simple application however you may wish to go for option 3, 4 or 5. I must now inform you that they will all require basic HTML knowledge – accept this as I had to!

Fortunately, as you are already proficient in the art of programming, HTML will not be too difficult to grasp. Further, I was grateful to find numerous free applications that took away the stress of making simple HTML pages.

In the next section, I will deal with how to make a HTML help file that can be read through the customers HTML browser. Details on how to put it on the internet will be explored later (for now, it is appropriate to test it locally i.e. on your own computer). Following that, I will show how you can produce an stand-alone HTML help file (i.e. option 4 above)