Offering Online Help

The area of online help is a huge topic, and therefore in this section I’d like to focus on the usability issues of your software interacting with the online help system. First and foremost, remember to include an online help system. Don’t take the easy way out and simply have an About item on the Help menu. That’s not good enough. Users need a way to get help when using your software.

However, and this might seem like a contradiction, if you design your software properly in terms of usability, then ideally you shouldn’t need an online help. Yet, please do include a complete, extensive online help system. The logic is that you want to go at the usability from two directions: Make your software easy to use, and provide an excellent online help system. The two aspects will then complement each other nicely. Don’t skip the online help just because you think your software is incredibly easy to use, and certainly don’t make your software hard to use…well, I don’t even need to say that.

Windows includes two primary help engines:

• WinHelp This is the old, original help system. However, Windows actually has two versions of this, a really old original one and a slightly old one. The really old one is c:\windows\ winhelp.exe, which is a 16-bit application intended for (eek!) Windows 3.1 and earlier. The slightly old one is c:\windows\winhlp32.exe, which appeared with NT and 95. Both versions of WinHelp read files that have an .hlp extension.

• HTMLHelp This is a newer online help system from Microsoft, and it reads files with the extension .chm. The help system uses HTML files under the hood, which are much more versatile than the older hypertext help files with WinHelp. The executable for HTMLHelp is hh.exe, which is basically a wrapper around Internet Explorer. (You can see this by running hh.exe myfile .html, where myfile .html is some HTML file.)

In addition, the Java system includes its own online help engine, called JavaHelp. These days, skip WinHelp and go right to HTMLHelp. A lot of programs still use WinHelp, but they seem antiquated. The last thing you want is for your users to open up the online help and think your program must be old simply because the program uses an older online help system!

When you start building your online help, here’s a pretty good rule to keep in mind:

RULE

Online help is a reference guide. Therefore, structure your online help as such, and don’t expect (or require) the users to read it from start to finish.

And with a good online reference guide, of course, comes a good index. Take time to build a thorough index, using as many keywords as possible. Don’t just make the index and alphabetized table of contents. I know I get frustrated when I open up the index to an online help and see only 10 entries. I want to see a lot of entries in the index. And if the index doesn’t have what I need, then I expect to find my item in question by using the search engine. Fortunately, however, with most help systems you don’t have to implement a search facility; the help engine will perform the searches for you on the user’s computer.

In addition to a reference guide, you might also consider a pretty-darn-good tutorial. Unlike a reference guide, a tutorial usually needs to be read from start to finish, and the user really can’t just dive into the middle. That’s fine, but make sure you set up the tutorial to be easily navigated. The help engine provides the necessary navigation tools for you, provided you build your online help using the appropriate help-building tools.

If you decide to include a tutorial, however, I recommend two important points:

• Make sure the tutorial is easily accessible. Some people like to put a menu item right on the Help menu for the tutorial. I also like to include my tutorial right in the table of contents of the main help, usually right at the beginning.

• You might consider including a tutorial directory in your product installation, where you include the sample files for the tutorial. You could have several subdirectories, one for each tutorial lesson, showing the sample files in various stages of completion.

However, if you choose to include sample files, I recommend also including a backup directory under each subdirectory containing copies of the tutorial files. The reason is that if the user is working through the tutorial, then he might accidentally modify the sample files, forever changing them. You should probably also include in your tutorial instructions for copying the tutorial files to the user’s own directory, leaving the backups present just in case the user modifies the original tutorial files.

In addition, you might consider a functional section in your online help. This is a section organized by task. For example, in the functional section of the online help for a word processor, you might include information about how to do higher-level tasks such as mail merges or creating templates. Such tasks are usually more than just toolbar button clicks; they require sequences of primitive actions. However, they are common uses for your software, and you want your users to be able to quickly learn how to perform these actions.

The Pitfalls of Converting the Manual to Online Help

Several years ago, I reviewed a bunch of online help programs for a magazine. A couple of the programs prided themselves in the way they could convert a manual to online help. Now I don’t want to badmouth any software programs, and the reality is that this review was circa 1994, and since then the surviving programs have evolved greatly into software that’s pretty darn good. But as with any software package, you get out of it what you put into it. When designing online help, a lot of people think the easiest way is to simply convert their manuals into some kind of online hypertext document.

This is a bad idea. Researchers (and laypeople, for that matter) have found that people use books very differently from the way they use online help. Online help is, by nature, hypertext-oriented, and regardless of the intentions of the help designers, people simply don’t read them cover to cover, start to finish. People might use a tutorial to get up and running, and from there they will use the online help as a reference guide.

The hypertext issue is particularly problematic. Some people, when converting their manuals to online help, will have the help generator automatically turn every indexed word into a hyperlink. The problem is that the users won’t know if they must click every link or not in order to understand the topic. For example, suppose I’m reading the entry on the Discombobulator, and in the middle of a sentence the word create is underlined as a hyperlink. Am I required to click the link and first read the entry called Creating a Discombobulator before I understand the topic I was previously reading? See, a hyperlink creates a disjoint in the reading. (Instead, a better choice is to include a section of related topics somewhere in the page, probably at the end.)

Further, I’ve seen occasional online help entries that say, “See the next chapter for more information.” But what’s a chapter in the online help world? This particular online help offered no table of contents, and so I was completely lost. I had no idea where the “next chapter” was. And on a similar note, the same online help said, “As you learned in the previous chapter,” which implied that they expected me to read the whole thing cover to cover, which I wasn’t trying to do.

Therefore, simply converting a manual to online help is nothing more than a lazy attempt at getting something out the door as soon as possible. Take some time to make a good online help.

And finally, remember that going in the other direction is at least as bad, if not worse: Don’t just print up every page in the online help to create your manual and then bind and ship the manual with the product. (At least one major software vender does this.) That’s a major waste of paper and a serious disappointment; I feel cheated.

Finally, remember to integrate your online help into your application. Don’t just include a Help menu. Also include context-sensitive help. If the user is performing a certain action or displaying a dialog box, allow the user to press F1 to open up help specific to the topic. And in your dialog boxes, also include the famous little question mark icon in the upper-right corner, allowing the user to click the button and then click an item in question on the dialog box. This will open up a small window providing help for the user. (The way to implement this depends on your programming tools. Most SDKs these days include a class or some easy way to implement the feature.)

What about PDF?

It all started years ago. Somebody decided that they could take the easy way out and ship a single set of PDF files that would suffice as both the manuals and the online help. A lot of usability experts have criticized PDF files, and now I’d like to chime in.

First, I think PDF is a great standard and has its place. The problem is, people don’t seem to understand where PDFs belong. Please do not—I repeat, do not—simply offer up your online manuals and help as PDF files. Here’s the problem: PDF files are a fixed layout (unlike HTML, which is far more suited to the computer screen). For the most part, reading PDF files is more or less painless, unless you are forced to read multicolumn pages.

Multicolumn pages are a nightmare on the computer screen, because you are forced to continually scroll down, then back, then down, then back. Figure 14.2 shows a multicolumn page in Acrobat Reader of a PDF file that I created. You can see that when you’re reading the first column, you have to scroll down to get to the rest of the column and then scroll back up to the start of the second column.

Figure 14.2: The text is divided into columns, making scrolling a pain.

Figure 14.3 shows another problematic text. This is an index from another Sybex book. When you print this (as Sybex intended), you’ll be fine. But reading it on the screen is difficult. In this case, you’re not just trying to read from start to finish. Instead, you’re trying to scan the columns with your eyes, noting the alphabetical order, as you search for the entry you want. One of the entries is Array class. You can see that that entry will come after the text that’s visible in the first column but before the text in the second column. So do you scroll up to find it or down to find it? Who knows; it depends on which column the text is in. Because the first main entry in the second column is ArrayTypeMismatchException, my first inclination would be to scroll up, expecting to see Array class toward the top of the second column. But, in fact, the entry is at the bottom of the first column. Try again.

Figure 14.3: This PDF has an index divided into columns, which is a nightmare on the screen.

Wide columns are an even bigger problem. Remember, PDF is intended for printing. And some people might want to print their pages in Landscape orientation. But with wide columns on the screen, you have to either continually scroll left and right as you read the text or shrink the page down so that the column fits, possibly making the text too small to read! Figure 14.4 shows an example of this problem.

Figure 14.4: This text is too wide for the screen. But if you shrink the page so that the text fits, the font will be too small.