Technical Writers’ Companion

Traditionally, most online help systems consist of two panes: a navigation area and a separate topic area.

The navigation area is typically positioned on the left side, and the topic area on the right side. For help systems written in left-to-right languages, this order matches the logical sequence of operations: first choose, and then read.

Within the navigation area, users can typically switch the view between a table of contents, an alphabetical index, and full-text search.

The following picture contrasts the most common implementations:

▪horizontal tabs

▪vertical tabs

▪expandable sections

To separate the navigation area clearly from the topic area, you can use:

▪a fine line

▪a light background color on the navigation area

Note:
Don’t use the background color on the topic area. Because the topic area is larger than the navigation area, a colored background would be too dominant here. In addition, a dark background might impair readability, which is more serious in the topic area.

A good solution is to use a gradient instead of a solid background color. A gradient is less obtrusive but provides enough contrast on the borderline between both areas.

Some help authoring tools and help viewers allow you to set the default width of the navigation area.

▪Make the navigation area as wide as necessary but as small as possible. In particular, don’t make it wider than needed for the longest entry in the table of contents.

▪If your help will be translated: Bear in mind that in most other languages, texts are slightly longer than in English.

▪On a standard computer monitor, the relative width of the navigation area should typically be in between 25% and 33% of the help window’s total width.

Some help systems hide the navigation area by default, especially if there’s very little screen real estate available or if help is embedded into the program window as an integrated help pane. Users can then use a special button to toggle the display of the navigation area.

The advantages of a hideable navigation area are:

▪When the navigation area is hidden, the help window needs less screen real estate.

▪When the navigation area is hidden, users can fully focus on the content of the topic. They are less tempted to go to other topics that they see in the table of contents.

The disadvantages of a hideable navigation area are:

▪Hiding and unhiding requires additional interaction.

▪When the navigation area is hidden, users don’t see the global context into which the topic that they’re reading is embedded.

▪When the navigation area is hidden, users don’t find related information unless there are links to this information in the topic.

▪Novice users might be completely unaware that they can open an extra navigation pane—even if the button can easily be seen.

Help on the Internet and on mobile devices often doesn’t use a separate navigation area at all but switches between the topic view, the table of contents, the index, and search results. Only the search box is typically available on all pages.

The advantages of switching between content and navigation are:

▪The help window only needs a minimum of screen real estate.

▪When navigation isn’t visible, users aren’t tempted to go to other topics that they see in the table of contents. Instead, users can fully focus on the content of the topic.

▪Compared to a hideable navigation area, this approach is more consistent and less confusing for novice users. The size of the help window and the size of its panes always remain constant.

The disadvantages of switching between content and navigation are:

▪Switching requires additional interaction.

▪When navigation is hidden, users don’t see the global context into which the topic that they’re reading is embedded.

▪When navigation is hidden, users don’t find related information unless there are links to this information in the topic.

If you have a lot of content, and if you don’t have to embed your content into an existing web site, use the traditional version that places the navigation area and the topic area side by side.

Make the table of contents hideable or hide it by default only if you have very little screen real estate, particularly if the help window is embedded into a program window.

Use the model of switching between different views for the topics, the table of contents, the index, and search results if:

▪you only have a small number of help topics

▪you need to embed online help into an existing web site

▪help will be used on devices that have a small screen size, such as mobile devices

Note:
Some help authoring tools don’t support all types of layouts.