Windows Online Help Options

Online help has been a part of Windows since its initial release, back in the days when applications and operating systems still shipped with printed manuals and never required more than two floppy disks. I really miss those days. That sense of touch; the cold, smooth pages in my hands. I remember the first Windows software I ever purchased, a newly released "Personal Information Manager." It had everything I needed, including a 400-page user's guide and reference manual. Sheer delight.

Those days are gone, replaced by online help systems and HTML readme files. Now you buy books like this one to bring back that included-user's-guide feeling. But you can do a lot with online help, especially these days with the ability to include dynamic, active content in online help pages.

WinHelp

The original Windows help system was WinHelp. It included simple formatted help pages with hyperlinks to other pages. A separate "contents" file added table-of-contents support; you had to ship the ".cnt" contents file with the ".hlp" file as a set. These basic help files were (and in many ways, still are) good enough for most users' needs, and they are still supported by all releases of Microsoft Windows.

To build a WinHelp file, you needed to craft your pages as RTF (Rich Text Format) files, a document format supported by Microsoft Word and most other word processors. It was great for writing the main content of your help files because it was just word-processing content. Unfortunately, preparing the different elements that supported the help-specific features, like hyperlinks, was a little more involved. It required that special codes and symbols be precisely formattedsome as hidden text, and some as footnotes. This system worked, but it was not always pleasant, especially when you accidentally erased a piece of hidden text that you didn't even know was there.

Some third-party companies sold tools that made WinHelp development a little easier, either by generating the RTF content for you, or by interfacing with Microsoft Word. And to get to the advanced features supported by WinHelp, you really did need to defer to one of these off-the-shelf products, a pattern that would continue into future help systems.

HTML Help

RTF documents are so 1980s. When the Internet started sweeping the world with its ability to generate beautifully formatted pages through the common HTML tag-based language, Microsoft decided to upgrade its help system to one that used standard HTML documents: HTML Help. As its name implies, HTML Help is truly HTML-based. Anything that generates HTML can generate HTML Help content: third-party web-page designer tools, word processors, your own custom applications, and even Notepad. As usual, some vendors designed tools specifically targeting the HTML Help system.

HTML Help is better than WinHelp, due to its dependence on HTML and other related technologies. Each page of your online help file is a separate HTML page/file. Hyperlinks to other help pages are standard HTML hyperlinks. And HTML Help employs most of the features used in any web page, including Cascading Style Sheets and Java scripting.

Compiled HTML Help files have a ".chm" extension, and a single file includes primary content, the table of contents, and a predefined index of terms. We will use HTML Help technology to add online help content to the Library Project. I'll skip the details of the system until a little later in the chapter.

Microsoft Help 2

Most applications sold as of this writing use HTML Help, but not all. One big exception is Visual Studio itself. Its help system, Microsoft Help 2, combines HTML and XML content into a set of collections that work together as one. If you've installed the full version of SQL Server on a system with Visual Studio, they together share a common help interface. You can even search for pages in both collections at the same time.

Microsoft makes a "Help Integration Kit" available for developers who wish to merge their own content into the Microsoft Help 2 system. This is most useful for vendors who develop third-party controls and tools that integrate with .NET or SQL Server.

Assistance Platform

Windows Vista will use a new help system called Assistance Platform. The initial Vista release will use the new system for all operating system online help. Unfortunately, Microsoft will not have a development platform available for Assistance Platform until after Vista comes out. If you want to develop applications for Windows Vista, and have them ready in time for the Vista release, you will need to use HTML Help for the online help content. Microsoft will release a help support system once Vista is out so that third parties (that's you) can develop Assistance Platform content.

Other Methods

Not every application uses these Microsoft-defined help systems. Some applications include no online help at all because they are designed by bad people. No, I'm just kidding. There may be instances where online help adds no value to a program. But it's usually best to include some sort of written assistance.

Stand-alone HTML pages are just one step down from HTML Help files, and are a viable alternative for simple applications, or those hosted on a web site. You can use other standard formats, such as word processing or text documents, if you just don't have the resources to generate true online help files. And of course there are books, which will get my attention.

Visual Studio includes a feature that lets you generate documentation from the XML comments added to each member of your class. (I don't discuss this in this book; see the Visual Studio online helparen't you glad it's therefor additional information on "XML Comments.") Don't even consider using this for your own user documentation needs unless you are developing class-based components for use by other developers.