Designing Web-based Embedded Help

  by Scott DeLoach

Embedded help, as seen in Microsoft Money 99 and HTML Help Workshop, allows users to receive assistance without leaving the product. However, it requires close coordination between software developers and technical communicators. Difficult issues such as how, where, and when to present the information must be resolved. Beyond conference presentations and workshops, little information exists on how to make these decisions and how to design embedded help.

Overview of Embedded Help
Embedded Help is Help that appears within the application rather than in a separate Help window. This design allows the user to receive assistance without leaving the product. The first example of embedded Help to gain much attention was Microsoft Money 99. When the user selects "Help Topics" from the Help menu, the Money 99 Help attaches to the right side of the application. It offers tutorials, explanations, and demonstrations to help the user use and learn Microsoft Money.

Source Empowerment: An Embedded Help Design Case Study
In this session, I will discuss how I designed embedded Help for Ceridian Source Empowerment. Source Empowerment is a web-based employee self-service application. Using Source Empowerment over the Internet from their work computer, home computer, or company kiosk, employees can access and modify their HR records, request vacation time, sign-up for a seminar, or change their benefits. I will explain how the Source Empowerment embedded Help system uses JavaScript to provide:

  • context-sensitive help
  • active assistance
  • progress tracking

All of these features are provided for Internet Explorer 3+ and Netscape Navigator 3+ without any user installation.

I will also explain how issues such as help content placement, window size (and resizing), interactivity between the help, the application, and the user, and overall help system design were approached and handled.

Source Empowerment embedded Help screenshot

Context-sensitive Help
At this time, there is not a standard method for providing context-sensitive Help in HTML. For Source Empowerment, I decided to use JavaScript to create a modal design. When the user clicks the "Help" button, the application enters Help mode. The Help icon changes color (from orange to blue), and the left frame changes from navigation links to screen-level help information. While in Help mode, the user can press the Esc key or click the Help icon again to close the Help. My design assumption is that when the user clicks the Help icon, they have a question about the current screen. Therefore, they are not currently interested in viewing another page and the navigation links can be temporarily removed.

Screen-level help topics serve two purposes: they provide a brief description of the screen and links to related tasks. The screen description allows the user to verify that they are on the correct screen. The task links help to highlight common or useful but unexpected features. For example, the Personal Information screen (as seen in the screenshot above) can be used to change your marital and/or military status and to add any missing information to your HR record. However, a change in marital status may lead to changes in your W2 deductions and your health benefit plan. These related tasks are also included in the task list on the Personal Information help topic. To create embedded Help, you will need to maintain a close working relationship with application developers. To add embedded Help to a Windows application, the developer can embed an Active X web browser control into the application. If you are creating embedded Help for a web-based application, the developer can use JavaScript (IE/Netscape) or VBScript (IE only) to open your Help topics. The Help files will need to be created using HTML.

Active Assistance
Active assistance is help information that automatically appears as the user selects different interface elements. In Source Empowerment's Help mode, the field-level help topics automatically appear as the user moves around the interface. In the screenshot, the user has selected the Birth date field. If they click in the Ethnicity field, the ethnicity help topic appears.

My goal is to provide support without distracting the user from their task. Users do not like to open Help: it takes them away from their task and they don't like to admit that they need help. By automatically displaying Help topics, Source Empowerment allows users to benefit from the support information without leaving their task and without specifically asking questions.

Progress Tracking
In Source Empowerment, procedural help topics use JavaScript to sense which step needs to be performed and whether steps have been skipped. As the user completes a step, a blue arrow moves to highlight the next step. If the user skips a step, the step is marked as skipped (in some cases, a step may not need to be performed: the information could be correct "as is," or a step may not apply to the situation).

I use progress tracking to build user confidence and satisfaction and to help prevent errors. For longer tasks, users need to know that they are making progress toward their goal. Otherwise, they may lose interest and/or confidence in the application and give up. Often, users will lose their place in the task and accidentally skip or incorrectly complete a step. Automatically tracking their progress makes matching the current step to the interface much easier and therefore makes it easier to successfully complete the task.

Recommended Resources
The following Web sites and books provide information about embedded Help or related technologies:
Hyperviews:Online, the Online SIG's quarterly newsletter, features articles on all facets of online Help development, including embedded Help.
The WinHelp e-mail discussion group archive. If you have a question about online Help, this should be your first stop.
Our Web site includes information about HTML-based Help and a "links" page with links to online help, tools, usability, GUI design, instructional design, and rhetoric Web sites.

Lie, Håkon Wium and Bert Bos, Cascading Style Sheets: Designing for the Web, New York, NY: Addison-Wesley, 1999.
The guide to Cascading Style Sheets, from the authors of the CSS standard.

Holzner, Steven, JavaScript Complete, New York, NY: McGraw-Hill, 1998.
This book focuses on version 4+ browsers and provides good information about Dynamic HTML.

Heinle, Nick, Designing with JavaScript, Sebastopol, CA: O'Reilly & Associates, 1997.
A great introduction to JavaScript.


Scott DeLoach
Founding Partner - User First Services, Inc.
User First Services, Inc.
45B South Peachtree Street
Norcross, GA 30071

Scott DeLoach is a founding partner of User First Services, Inc, an Atlanta-based consulting company that specializes in designing and creating user assistance. Scott has received two STC International Online Competition Awards for interactive user assistance systems, and he currently serves as the STC International Online SIG Manager. He holds a Master's degree in Technical and Scientific Communication from Miami University.