Written by Jerry Stern
Chief Technical Officer at Science Translations

In the brave new world of always-online software, help files have changed. We used to write HLP files. Now, it’s compiled hypertext, or CHM files, or sometimes, it’s a web page, and not much else. Format shouldn’t affect function, but it does–the industry is getting horribly sloppy, and have forgotten that help files are about teaching, and are not about searching.
What has to be in Help?

A help file, regardless of the format, needs some basic structure. Certain questions have to be answered; they’re the same questions that applied in writing class. When writing Exposition, or writing that explains, or Reporting, writing about events, include as many of these as possible: Who, What, When, Where, Why, and How. Mostly, help files won’t include a lot of ‘why’, but try for all of them. When writing a help document, start with this outline, and expect to change the headings when it’s almost finished:

• What does the software do? Include a short description of what the software does. This isn’t a sales pitch–it’s an introduction to the software, what the workflow of the program is like, and what kind of projects are possible in the software.

• How do I get started? Include the simplest possible project, how to start creating a task, how to learn about the program, and how to save, export, publish, or display the finished task–not all of these apply to every program–choose the simplest case, and explain it.

• Where are the commands and functionality? Tell the user where you’ve hidden all that wonderful functionality, in toolbars, in the menus, in keyboard shortcuts.

• When do I use these menu choices? Include the basic sequence of steps in an introductory project.

• Why do I choose to do things this way? This is why your software matches the workflow for a specific task, best to follow a specific sequence, or it can be a description of several sequences of tasks that will work, using your software product.

• Who published it, and who are they? Include contact information, links to additional help, tutorials, and updates.

First things First

When writing step-by-step instructions, sequence is your top priority. Here’s a horrible example:

You can change the settings for communications. Check off “use alternate port” in options.

What’s wrong with that? Well, it’s vague–it doesn’t say why or when you would use these instructions. It’s out of sequence–the steps are not in the order that they become visible to a user; first list where to go, then what to do. Not what to do first and then where to go–that encourages reading backwards while the user skips forward for navigation, and back again for the option to click. Finally, it looks like the option doesn’t match the software menus, and it’s not totally clear what the menu names are labeled.

Try again:

When the software won’t connect to the remote server, an alternate port may be used. Go to the Tools menu, choose Options, and at “Use Alternate Port”, add a checkmark in the option box. Click OK to close the dialog.

What changed? First, there’s a short explanation of ‘what’ at the beginning–in real software documentation, it should be more specific. Second, the steps are strictly in the same order as a user would see them on-screen, and no steps are left out. Third, the name of the option is precisely the same as in the menu, including capitalization and underlined menu shortcut keys.

Advanced Topics

Here’s a far more complex example, taken from a WordPerfect Magazine article I wrote, way back in 1992, about creating greeting cards in WordPerfect:

Begin at the WordPerfect document screen. Press Format (Shift F8),
(2) Page, (7) Paper Size/Type, (2) Add, and (9) Other. Type ‘Card’ and press(Enter), then (8) Labels, (Y) Yes.
A new menu will appear for the label definition.

The format for magazine writing of this kind is extremely precise. Every menu label appears, with the shortcut key, and every keystroke is included, with enough information at the end to let the reader see that they’ve arrived at the right place.
This level of precision can add confusion when the program is translated. The number selections work in every language, but the letter options may not be consistent. Be careful when translating sequences of menu choices, or plan ahead during menu design to keep steps and shortcuts consistent in all languages.
Should you use this type of magazine style for help topics? On some topics, yes. Think of a short article, maybe a few paragraphs, for an extended example of how to do a task or create a project in your software. It’s a great introductory lesson, but include every step, and choose a very basic first project for the example.

Describe what Menu Options Do

I frequently wonder what a menu entry does in a program I’m trying out. I look for the matching entry in the help file. For example, under File, Export Stuff, I’ll find this:

Exports stuff in a file.

Wrong, on so many levels. First, it tells me nothing that isn’t already in the name of the menu entry. Second, it doesn’t tell me what or when or any of the other basic answers. Try again:

File, Export Stuff: Saves the current project in a special format that provides __fill-in benefit here__. The Stuff format is used for ___. This function is also known in other programs as ‘Save As’, ‘Publish To’, or ‘Send to a Service Company’.

Huh? What’s all that stuff in the last line for? Well, that fixes the next problem, of searching a help file for a function you know exists in a program, when you don’t know the name. It’s the elementary school complaint about dictionaries and spelling–“how can I look up the spelling if I can’t spell it?”

Well, when you search help for what you think an option or function is called, and don’t find it because the author has been very consistent in always calling an export an export, what happens? Not a whole lot, beyond thinking nasty thoughts. Telepathy doesn’t help; keywords do. Those alternate names are there for searching the help file by keyword.

In the Deep End without a Paddle

Many programs now have only hypertext help with search, and no table of contents. It’s very Wiki, and worthless for learning a new program. In these monsters, you can press F1 for help, and if anything happens at all, there’s a pop-up of search titles related to a topic. It should be a topic related to the screen that was displayed when F1 was pressed. That’s ideal, and that was the standard form of help, 10 years ago.

But now, too many programs display nothing but pages and pages of unfiltered word matches for every attempt to search. Make sure that the novice-level information doesn’t get buried; the users that need advanced help know how to search, and are already sold on using your program. Novice users don’t know your program, may not have bought it yet, and are easily discouraged. Keep it simple for them–quick help searches should lead to intro-level topics, and then to advanced, and not just dive into the greatest possible depths of trouble-shooting chit-chat.

No matter what the format of the help documents, include a table of contents or a good index, include an introductory lesson, and remember that help isn’t a list of dialog box names–it’s a directory of how to use your software product.

Jerry Stern runs Startupware.com, and is online at www.PC410.com.