Which online help format?

Print topic Print topic Previous topic  Next topic

You can use plain HTML plus JavaScript to create an online help system that can be viewed with any web browser, or you can choose a format that must be viewed with a special help viewer.

Some formats let you store help either locally on the users’ computers or on a web server. Other formats work exclusively locally or exclusively on a web server.

Choosing the right help format isn’t a decision that you, the author, can make on your own. The product must be able to install and to call the help system, so always involve product development at an early stage.

Expand /Collapse All Subsections

Should help be local or on a web server?

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

Should you create browser-based help (plain HTML) or a special, compiled help format?

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 (see Tool Guide: Help authoring tools).

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.

Help formats

Help format

Characteristics

HTML

Browser-based help.

Can be stored locally or on a web server.

Works on all platforms. Most common format for web applications.

HTML Help

(CHM)

Compiled Microsoft help format.

Most common format for windows programs.

Help 3
Microsoft Help Viewer

(MSHC)

Format used by Microsoft in Visual Studio.

AppleHelp

Standard Mac OS help format for Apple Help Viewer.

Adobe Air Help

Uses Adobe Air to generate an advanced help system, which also includes social features.

Only a few help authoring tools can generate this format.

Proprietary help formats

Some programs, platforms, and help authoring tools have tried to establish their own, specific help viewers and help formats. Most of these systems aren’t very popular.

Usually, these systems are HTML-based and provide a collapsible table of contents, an alphabetical index, and search.

Examples are: JavaHelp, Oracle Help, Eclipse Help.

Wiki

Some wikis can display their content in a way that looks almost like browser-based help, including a hierarchical table of contents.

Embedded help

Assistive texts embedded into the user interface (see also Can you embed help?).

HTML is usually the preferred format, but the texts may also be stored in a program’s resource files or in any other file that can be loaded and rendered at runtime.

Winhelp

(HLP)

Obsolete Windows help format; was replaced by HTML Help in 1995.

PDF

XPS

No genuine help formats.

The layout of most PDF and XPS files is optimized for printing. For example, the layout typically includes page breaks and page numbers.

It’s possible to create PDF and XPS files that look almost like online help. However, be aware of the fact that you then also need to restructure your content. If you’ve written a manual, it’s a manual—no matter which format you use for display.

EPUB

AZW

No genuine help formats.

Designed to display books on screen.