Technical Writers’ Companion

The advantage of storing help locally is that it’s always accessible even if users don’t have an Internet connection. Some users also prefer to have all parts of a program, including help, stored on their own computers just in case the developer of the program stops supporting the program or goes out of business.

The advantages of storing help on a web server are:

▪You can easily keep help up to date. Users always see the latest version.

▪You can integrate social features into help (see Should you add social features?).

▪You can use the log files of your web server or some special web analytics software to obtain valuable information on the users’ behavior and information needs. Later, you can use this information to further optimize both your help system and your product.

In particular, log files may show you:

▪which search terms are used most often

▪which help topics are accessed most often

▪which routes users take through help

Most help authoring tools can generate browser-based help that has the same features as compiled help, such as a collapsible table of contents, an alphabetical index, and search.

Advantages of browser-based help are:

▪it can be viewed with any modern web browser

▪it’s platform independent

▪it doesn’t tie you to any proprietary technology

▪it can be stored both locally and on a web server (however, when installed locally, there might be some compatibility issues, depending on the used browser and its security settings; to avoid this, you might need to install a local web server)

Advantages of special, compiled help formats are:

▪close integration with software (embedding, help calls)

▪particular look and feel

▪usually it can be created without a special help authoring tool by using plain HTML files and a free compiler

▪some compiled formats already come with advanced navigation and social features

Recommendations:

▪When possible, create browser-based help.

▪Don’t create HTML pages manually but use a dedicated help authoring tool that adds a collapsible table of contents, an alphabetical index, and search.

▪If you want to use context-sensitive help calls, make sure that browser-based help can be opened on any page. Some low-cost help authoring tools generate help files that don’t support this.

▪If you need very close integration of help with the program, or if help needs to have a particular look and feel, use the compiled help format that’s been designed for your program’s platform.