Designing Embedded Help

  by Scott DeLoach

Embedded Help is a new, cutting-edge approach to delivering online Help. However, there are few examples of embedded Help for technical communicators to explore. Embedded Help is very different from other types of online Help: it requires very short and focused topics that do not rely on a traditional organizational tool such as a table of contents or index. This paper provides and overview of embedded Help, discusses two examples, and explains how technical communicators can design embedded Help.

What is Embedded Help?
Embedded Help is Help that appears within the application rather than in a separate Help window. One of the early examples of embedded Help was the Help system in 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. The Microsoft Money 99 Help offers tutorials, explanations, and demonstrations to help the user use and learn Microsoft Money.

Figure 1. Embedded Help example (Microsoft Money 99)

Embedded Help can also be created for web-based applications. In Figure 2, a frames-based web application actively displays context sensitive Help when the user selects different form fields.

Figure 2. Embedded Help example (Web-based application)

How Do I Create Embedded Help?
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.

How Do I Design Embedded Help?
As you can see from the examples, the embedded Help area can be very small. Your Help topics will need to be very focused. Try to provide short descriptions with simple examples. Also, consider using a small sans serif font such as MS Sans 9 point and minimize the space before and after headings. Embedded Help should be designed to take advantage of full-text search, related topics links, and layering. For larger Help systems, make sure that the full-text search box is easy to find and use. Related topics links can be used to help the user explore additional information. For example, a topic about importing files should include a list of file types that can be imported. At the end of the topic, you could provide a link to a conceptual topic about importing files for new users and a link to an advanced topic explaining import options for experts. Finally, you could layer the topic information by providing additional information when the user selects a file type from the list.

What Do I Need to Know?
To create embedded Help, you should be very comfortable with HTML. If you are creating Help specifically for a version 4+ browser, you should also consider learning about JavaScript, Dynamic HTML (DHMTL), and cascading style sheets (CSS). JavaScript can be used to create shortcut buttons that interact with the application. Or, you can use JavaScript with DHTML to layer information. CSS can be used to format your topics based on one set of rules, rather than formatting everything by hand.

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.