Design Specifications and Guidelines - User Assistance

HTML Help

Windows provides support for creating Help interfaces using standard HTML. HTML Help replaces the WinHelp support included in previous versions of Windows. While Windows 98 and Windows 2000 still include this support for backward compatibility, HTML Help is a better choice. HTML Help uses common Web conventions, providing a familiar and consistent way for users to learn to navigate through Help information. You can use HTML Help to support Help interfaces for both conventional and Web-style applications. It also enables you to easily include local Help topics as well as HTML pages on Web sites.

Use HTML Help Workshop to compile and compress your HTML Help files. You can also use it to create contents and index files for those files. For more information about Windows HTML Help Workshop, see the MSDN Online Web site at https://msdn.microsoft.com/workshop/author/htmlhelp/.

The HTML Help Viewer

HTML Help includes a special window called the HTML Help Viewer to display the Help topics that you write. Open the HTML Help Viewer to display a window and a toolbar. Below the toolbar, the window is split. The navigation pane is on the left and the topic pane is on the right, as shown in Figure 13.10.

Figure 13.10 HTML Help Viewer (click to enlarge image)

You provide primary access to Help topics through the Contents, Index, or Search tabs. You can also include access to specific topics through other interfaces, such as navigation links placed in other Help topics.

More Information

For information about authoring HTML Help files, see the MSDN Online Web site at https://msdn.microsoft.com/workshop/author/htmlhelp/.

To support user access to the HTML Help Viewer window, include a Help Topics menu entry on your primary window's Help menu. When the user clicks the Help Topics command, open the HTML Help Viewer and display it the last way it was viewed by the user. Alternatively, you can include commands that open the Help Viewer to a particular tabbed page.

You can define the size and location of a Help Viewer window to the specific requirements of your application. It is best to size and position the window so as to cover a minimum amount of space, yet be large enough to allow the user to read the topic, preferably without having to scroll. This makes it easier for the novice user who may be unfamiliar with scrolling. Keep in mind, however, that the user can override the font sizes and other formatting specified by the author. Make sure your Help screens remain usable when the user adjusts the color, font, and accessibility options in Internet Explorer, as these will affect how your content is displayed.

When designing your HTML Help topics, follow the standards set by the World Wide Web consortium for accessibility of Web content. Following these guidelines will ensure that your application is accessible to the widest possible range of users and compatible with automation tools. For more information, see the Microsoft Accessibility Web site at https://www.microsoft.com/enable/.

The Toolbar

The HTML Help Viewer toolbar includes a set of buttons that enable users to navigate, print a topic, and change the view of the window.

Toolbar Buttons in HTML Help Viewer
Button	Purpose
Back	Displays the previously viewed topic.
Forward	Displays the topic viewed before the user selected Back.
Hide	Hides the navigation pane.
Home	Displays the designated home topic (page).
Jump 1	Displays an author-defined URL location. The button label is customizable.
Jump 2	Displays an author-defined URL location. The button label is customizable.
Locate	Synchronizes the navigation pane with the currently displayed topic.
Options	Displays a menu of commands and viewing options.
Print	Displays the Print dialog box to support printing a topic.
Refresh	Updates the content in the topic pane with information stored on a Help Web site.
Show	Displays the navigation pane.
Stop	Stops downloading information.

The default toolbar buttons that appear in the HTML Help Viewer are Back, Hide (and Show), Options, and Print. You can include any others by defining them in your HTML Help files. For example, if your users access topics from the Web, you could add the Home, Stop, and Refresh buttons. You can also add your own customizable buttons. Avoid adding too many buttons, which can cause the toolbar buttons to wrap. You can also include the Back, Forward, Stop, Home, Refresh, and Print commands on the Options menu.

The Navigation Pane

When the user opens HTML Help, a navigation pane is displayed that contains tabbed pages for Contents, Index, Search, and Favorites. This provides a starting point for users to find Help information.

The Contents Page

The Contents page displays the list of topics organized by category, as shown in Figure 13.11. You can hide the navigation pane when the HTML Help Viewer displays your Help topics.

Figure 13.11 The Contents page of the Help topics browser

A book icon represents a category or group of related topics, and a page icon represents an individual topic. You can nest topic levels, but do not create more than three levels, as this makes access cumbersome, especially for novice or beginning users. Also try to limit the number of top-level entries to avoid making the user scroll excessively to see all the topics. Similarly, try to limit the number of topic titles you include under a top-level entry to 10 to 12 entries.

If the information in your Help system is targeted for most users, provide single-click access from the Contents page. Most users prefer this. Requiring users to double-click to access topics may provide more flexibility but at a tradeoff of simplicity. If you do support access methods other than single-clicking, consider changing the appearance of the Contents page. For example, you could include plus and minus buttons for expanding and collapsing the tree, or you could use different icons.

You can also customize the icons used for books and topics, either by choosing the ones that come with HTML Help or by creating your own. You might want to use different icons for different types of topics. Always usability test any icons you create, as well as the text that appears with them. Also consider the impact of your icon designs for international users.

You do not have to include all topics on the Contents page. Some topics, especially advanced or seldom-used topics, can be made available as links from other topics or through the Index and Search tabs. This keeps the table of contents simpler for users. Topics that are not essential should be removed from the table of contents. For example, if the subject is backing up a database, you might move topics about networking out of the table of contents.

Guidelines for Writing Contents Entries

The entries listed on the Contents page are based on the topics included in a set of Help files. Organize them to enable users to see the relationship between topics. Add titles that are brief but descriptive, and make sure the Contents entries correspond to the actual topic titles.

Shorter topic titles are more effective because they can be viewed fully in the navigation pane without scrolling, and usability testing has shown that shorter phrases result in better user comprehension. To improve readability of long topic titles, you can enable ToolTips.

It is generally a good idea to separate procedural Help from conceptual Help. Users who simply want to perform the steps of a task appreciate not having to wade through a lot of conceptual information. Within a procedural Help topic, you can link to Related Topics that contain conceptual information, as shown in Figure 13.12.

Figure 13.12 Link to conceptual information (click to enlarge image)

The Index Page

The Index page of the HTML Help Viewer organizes topics by keywords that you create for each topic, as shown in Figure 13.13.

Figure 13.13 The Index page of the Help topics browser

The user can type a keyword or select one from the list. When the user clicks the Display button, the topic associated with that keyword is displayed. If multiple topics use the same keyword, then another window is displayed that allows the user to choose from that set of topics, as shown in Figure 13.14.

Figure 13.14 Topics Found window

It is never a good idea to reference a specific index entry from a Help topic or from any part of the user interface. A modification to the Help index might not be propagated to the entire software system. There is no good mechanism for searching for references to a particular index entry throughout a product.

Guidelines for Writing Help Index Keywords

Since many users access Help information through the index, it is important to provide a thorough and effective list of keywords in your Help system. A keyword index should include terms for both novice and advanced users, should offer information at as many entry points as possible, and should provide thorough cross-referencing. When deciding what keywords to provide for your topics, consider the following categories:

• Actions the user might want to take (for example, copying, routing, saving)
• Subjects that might be in the user's mind when tackling a problem for which the topic is helpful (for example, files, networks, projects)
• Synonyms for the action and subject terms
• Software industry terms that might be familiar to the user

Another important part of the indexing process is to ensure that the same topics are referenced by related keywords. For example, if the keyword term "network connections" references seven topics, the keyword term "connections, network" should reference the same seven topics. Because checking for this type of consistency can be very time-consuming, it may be simpler to include a cross-reference, in this case "connections, network See network connections."

The following are the recommended guidelines for writing index entries:

• Keywords should be lowercase unless they are proper nouns (for example, use "files" and "File menu").
• Nouns should be plural unless the singular form is more correct (for example, use "programs" but not "Start menus").
• Verbs should be in the gerund form (for example, use "copying files," not "copy files").
• Keyword indexes should have no more than two or three levels of indentation.

Cross-reference keywords can be formatted to either display a certain topic or topics or jump within the index to the target keyword. For example, if the user clicks the "See network protocols" cross-reference, the Help system might display a topic that gives an overview of network protocols. Or, the keyword can be set up to actually move the user to the "network protocols" entry in the index. Usability testing indicates that users prefer the latter convention. This style decision should be made for the whole index; users should be able to count on consistent functionality from the cross-references in the index.

When an index keyword has more than one level, as in the example below, user expectations about the behavior of the first level vary.

device drivers
    configuring
    installing
    removing

Some users, especially those more familiar with WinHelp, expect the first level to display a comprehensive list of the topics found below the subentries. These lists, though, were often unwieldy, so HTML Help displays the subentries and their topics in a more manageable form. Setting the first level to jump to itself (inserting the keyword itself as the target keyword) creates a keyword that, when selected, instructs the user to choose one of the subentries below. Again, this is a style decision that should be made early and followed consistently to avoid user confusion.

The Search Page

The Search page, as shown in Figure 13.15, provides a full-text search capability that allows the user to search for any word or phrase in Help. This capability requires a full-text index file that you can create when building Help or that the user can create when using the Search page.

Figure 13.15 The Search page of the Help topics browser

You can offer simple or advanced search support. Use simple search for most consumer applications and advanced search to support Boolean-style queries for programming references or other technical documentation. Advanced search also enables the user to sort the Topics Found dialog box by clicking the Title, Location, or Rank columns.

You can also exclude words from being searchable. This allows you, the Help author, to exclude words from the search results that are inappropriate. For example, you could define the word "the" to be excluded so that a search for the word "the" returns nothing, but a search for "the device" returns the topics that contain both words.

A location column also appears in the search results. This column displays the title of the Help file. This is the word or phrase you author between the <title> and <\title> tags. In this way, users can differentiate between similarly worded topics that refer to different features. For example, if the topic "Adding Hardware" is listed twice in the search results, the two listings might be for "Plug and Play" and "Modems."

The Favorites Page

This page allows the user to create a personalized list of favorite Help topics. When the Topics pane displays a topic the user would like to keep for future reference, the user can switch to the Favorites page and add it.

The Topics Pane

The Topics pane displays the topics in your Help system. The HTML Viewer supports authoring in HTML to add a rich graphical presentation to your Help topics. In addition, the HTML Help Viewer provides other features to support the design of your Help content.

Help Topic Features

HTML Help also provides additional features that you can include in your Help topics.

Links

You can use a link to move from one topic to another within the same window, to another topic in the same Help file, or to a topic in another Help file. You should provide local alternate URLs for links for non-local (Internet) sites when the Internet connection is not available.

You can also link to a pop-up window. As with pop-up windows for context-sensitive Help, use this convention to display a definition or provide an explanation about the word or object the user clicks.

Links can also carry out particular commands; for example, a user could click a link to open a folder or a dialog box.

Always provide some visual indication to distinguish a link from non-interactive areas of the window. You can do this in the presentation of the link and by changing the mouse pointer to indicate an interactive element.

More Information

For more information about formatting links, see Chapter 14, "Visual Design."

Shortcut Buttons

The HTML Help window can include a shortcut or "do it" button that provides the user with an automated way to perform a particular step, as shown in Figure 13.16. Use a shortcut to open a dialog box, property sheet, or other object so that the user does not have to search for it.

Figure 13.16 A task Help topic with a shortcut button

Shortcut buttons not only improve efficiency for the user, they also reduce the amount of information you need to present. However, do not use the buttons as a substitute for doing the task or a specific step in the task, particularly if you want the user to learn how to perform the task without using Help in the future. For common tasks, you may want to include information that tells the user how to do the task, and shortcut buttons that make stepping through the task easier. For example, you might include text that reads "Show the Display properties" and a shortcut button, and then add a note at the end of the Help topic detailing the steps.

Pop-up Help

Pop-up Help can provide glossary definitions within a topic. By providing hot text within a topic, the user knows clicking it will result in an action. Pop-up Help streamlines the content so that only users who need the extra information view it.

Related Topics

Related Topics links provide access to topics of additional interest based upon the current topic. This feature corresponds to WinHelp Alinks and has the same dynamic characteristics of that feature. For example, a Related Topics link to a topic that is not present on the user's local disk will not show up in the Topics Found list. A Related Topics link for HTML Help displays a pop-up window if multiple topics are related. If only one topic is related, that topic is immediately displayed.

The Related Topics feature provides a key feature for a well-designed Help system. You should include entries for the most basic and useful information on the Contents page, then make less frequently used procedures and concepts available only through Related Topics. Define these topics to cover more in-depth information about a subject.

Topic Titles

Always provide a title for each topic. The title, defined by the HTML <title> and <\title> tags, identifies the topic and serves the user as a landmark within the Help system. Titles should be concise and fit on one line, if possible. The title is displayed when you search for a topic and in the Related Topics list. Try to make your topic titles closely match their titles listed in the Contents page. A user should not be surprised by the topic that appears after clicking a Contents entry.

Topics that appear in the Topics Found dialog box and Index page get their display entries from the topic title you define with the <title> tag. For example, suppose a topic is titled "Installing Plug-and-Play Hardware." Its Contents entry title might be "Installing Hardware." When the Topics Found dialog box appears, the title displayed to the user should be "Installing Plug-and-Play Hardware."

Outlining Buttons

Outlining buttons (plus and minus signs) provide organizational information within a topic. These buttons are used to represent a hierarchical organization, such as can be found in the Tree control, or a progressive revelation of information as the user wants to see it.

The Common Tasks topic in Figure 13.17 shows an example of progressive revelation. The Common Task topic contains general task titles that users can click to view task details.

Figure 13.17 Outlining buttons

Browsing Buttons

Although the HTML Help Viewer does not provide explicit browse buttons, you may want to create your own buttons to support the display of Help topics in a sequential order that you determine. This is useful for print books that are being ported to online versions. Users can click the browse buttons to move forward and backward through the material as if turning pages in a book. This technique can also apply to other types of sequential ordering of specific Help sections. For example, you might want to create a troubleshooter in Help and use browse buttons to let users navigate to the next or previous related Help topic.

Fundamentals of Designing User Interaction

Windows Interface Components

Design Specifications and Guidelines

Appendixes and References