Beginning with Windows 98, Microsoft has migrated from RTF-based Help (WinHelp 3 and 4) to HTML-based Help. Although HTML-based Help offers some exciting new opportunities for technical writers, it requires fundamental changes in how we create online help. This paper provides an overview of HTML-based Help and demonstrates some different design approaches.

What is HTML Help?
HTML Help is Microsoft’s replacement for WinHelp and the standard for HTML-based Help. It combines HTML files and an Active X control (hhctrl.ocx) to create a compiled Help system with a TOC, index, and full-text search tool. HTML Help can be used to display context-sensitive popups and Help topics for web-based applications or Windows applications developed in the latest versions of C++ and Visual Basic. HTML Help is used to provide Help for Windows 98 and IE 4, and it will be the Help system for all near-term Microsoft products. The previous WinHelp, RTF-based Help system will be supported until at least 2007.

Figure 1. HTML Help example (Internet Explorer 4 Help system)

Overall, HTML Help’s features are similar to WinHelp 4. The TOC, index and full-text search are all basically the same as WinHelp 4. Visually, the Help system is divided into a "tri-pane" window: the tool bar pane, the navigation pane, and the content pane. The Hide/Show button can be used to show or hide the navigation pane.

Potential Problems and Limitations
HTML Help has a few potential "gotchas" lurking behind the scenes. The HTML Help engine is really a subset of Internet Explorer, so users are required to have at least Internet Explorer 3.02 installed on their computer. Advanced features like Dynamic HTML require IE 4+. As with previous versions of Microsoft Help engines, Windows is also pretty much required. The navigation pane and its tabs are controlled by an Active X control called hhctrl.ocx. If the user does not have this control installed or if the Help is being accessed through the Internet, the control will be downloaded from the Internet. Normally, this takes about 45 seconds. If the user’s security settings do not allow downloading of Active X controls, the TOC, index and full-text search features will not appear. On the development side, HTML Help expects the author to use separate HTML files for each topic, often resulting in hundreds of HTML files.

If you are developing Help for a new Windows product that does not currently have Help and is being developed in the latest version of Visual Basic or C++, you should consider HTML Help. If you are developing Help for Windows 95 or 3.1 applications or if you are maintaining large legacy documentation sets, you should consider staying with WinHelp. If you are developing Help for a web-based application, you are much better off considering an HMTL-based Help approach.

What is HTML-based Help?
HTML-based Help is any online Help system created using HTML files. As opposed to HTML Help, HTML-based help does not normally require Internet Explorer or Windows. It also appears in a new web browser window (as opposed to HTML Help’s custom window). HTML-based Help is often developed with a combination of JavaScript and Java or VBScript and Active X. Active X and VBScript are normally used if the target audience is using Internet Explorer exclusively. If the audience is using a mix of operating systems and browsers (including older browsers) JavaScript or JavaScript and Java should be used.

What do HTML-based Help systems look like?

The biggest design influence for HTML-based Help is the target user browser. Internet Explorer 4+ provides the most flexibility because it supports Dynamic HTML, Cascading Style Sheets (CSS), and Active X. For IE 4+ projects, HMTL-based Help systems closely resemble HTML Help with a CGI search tool replacing the HTML Help search facility.

The example provided in figure 2 is a cross-platform HTML-based Help system for Netscape Navigator and Internet Explorer version 3+. This prototype appears in a standard browser window with the toolbar, status bar, and menu bar removed. The HTML Help tool bar and the button’s functionality has been copied using animated images and JavaScript. The table of contents was created using JavaScript, and the search tool is a CGI script. Unlike Active X and Java, JavaScript and CGI scripts are compatible with older browsers and are much faster to download. The completed version of this Help system features popups from the Help content and TOC, watermarks, and a guided tutorial of the web-based application it supports. All of these features were created using JavaScript.

How do I create HTML-based Help?

One of the easiest ways to create HTML-based Help is to use Blue Sky Software’s WebHelp. Using RoboHelp Office version 7, you can create WebHelp from HTML or WinHelp source files. A downside of WebHelp and many other HTML-based Help systems is that they do not include a search tool or index. These features can be added by using various indexing tools, including Microsoft’s Index Server, or using a CGI script. However, adding a search tool can be difficult and often takes a significant amount of time.

Figure 2. HTML-based Help example (Netscape and IE 3+ compatible)

Figure 3. WebHelp example (sample provided with RoboHELP Office)

What is Embedded HTML-based Help?
Embedded Help is Help that appears within the application rather than in a separate Help window. The first example of embedded Help to gain much attention was Microsoft Money 99. When the user selects "Help Topics" form the Help menu, the Money 99 Help attaches to the right side of the application. The Help offers tutorials, explanations, and demonstrations to help the user use and learn Microsoft Money. Embedded Help can be created for current version C++ or Visual Basic applications by embedding an Active X-based web browser into your application. The Help itself is created using HTML files.

Figure 4. Embedded Help example (Microsoft Money 99)

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

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

How Do I Create Embedded Help?
Embedded Help requires a close working relationship with application developers. To add embedded Help to a Windows application, the developer will need to embed the web browser Active X control. If you are creating embedded Help for a web-based application, your developer will need to use JavaScript (IE/Netscape) or VBScript (IE only) to open your Help topics. The Help files will need to be created using HTML.

As you can see from the examples, the Help area will be very small. Your Help topics will need to be very focused. If you are creating Help specifically for IE 4, knowledge of Dynamic HTML and cascading style sheets (CSS) would be useful. Knowledge of JavaScript would be very valuable as well.

Conclusion
HTML-based Help offers many exciting features for online Help developers. Web-based Help will allow us to maintain one copy of the Help on a web server. If we need to make any changes, we can update the Help in one place for all users. New technologies such as JavaScript, VBScript, Java, Active X, Dynamic HTML, and CSS will allow us to provide interactive and embedded Help. We are all at the beginning of a new learning curve for online Help, but time spent learning HTML-based Help tools and technologies will more than pay off for our users.

Recommended resources
Heinle, Nick. Designing with JavaScript. Sebastopol, CA: O’Reilly & Associates, 1997.
Zacker, Craig. 10 Minute Guide to HTML Style Sheets. New York, NY: Que, 1997.
STC Online SIG. Hyperviews:Online. www.pobox.com/~STConlineSIG.
WinHlp-l discussion listserv. See www.documentation.com for information about subscribing.

Scott DeLoach
Founding Partner, User First Services, Inc.
45-B South Peachtree Street
Norcross, GA 30071
Phone: (404) 520-0003

e-mail address: scott@userfirst.net
Web site address: www.userfirst.net

Scott DeLoach is a founding partner of User First Services (www.userfirst.net), where he provides documentation and interface design consulting and training to companies in the Southeast. Scott is the STC International Online SIG Manager and the Atlanta chapter Web Manager. He has received local and Society-level awards for online communication, including an Award of Distinguished Technical Communication in the 1997 Online Communications Competition.