Designing Winhelp Files

The mechanics of creating a help file are really pretty trivial. Click this, link that, index, compile. But after you have the mechanics of your tool figured out, what do you do with all this stuff?

That is where professional help developers stand out from the pack. This page has some tips for making your help file look and work better.

Remember, follow these guidelines as guidelines. There are few absolutes in design. But by following these guidelines, you avoid some of the most common help file design traps. This leaves you the time to discover new and different traps!

Parts of an Online Screen

How to Structure Help

How it Should Look

What Should be There

Indexing

Help files consist of windows and popups. Windows are the main locations your users spend their time in. An example Main window is shown below.

This is the topic that opens when the user selects this topic from the contents or the index. Notice how it has button, a non-scrolling region, descriptive text, and jumps. In the help file, when the user clicks on the To set the configuration options jump, they see a secondary window that looks like:

In Windows 95, you can have 5 secondary windows open at one time. Don't do that! It will make your user crazy. They will not know where they are and what to attend to. The screen will be so busy, they won't have any idea what to pay attention to.

The Windows 95 standard for help files is to always show the procedures in a secondary window with a yellow background. This is a great design idea. The user has the explanation about what they want to do in one place and then the How do I? information in another, but related, place.

When you use this design, make sure that the procedure window topic doesn't appear in the index, full search text, or the Contents. You want to control the path by which they get to the procedure. That way the user must read the explanation, cautions, etc., before they get to the how to.

top

How to Structure it - Sequencing

Browse buttons are the little << >> buttons. I have never come up with a satisfactory way to use browse buttons. I think they should step the user to the next related topic. But frequently that seems odd because at some point the user gets to the next, unrelated, topic. It may be the only way to do it.

If you use popups for definitions, and I think you should, don´t put popups or jumps in them. It makes it very hard for the user to know how they got there and difficult to go back. Very quickly, users get lost. When you lose them, they call customer support.

Speaking of popups and jumps, don´t link just because you can. Make the first occurance of the word the popup definition. Further uses of the word in the same topic should not be a popup. When every occurance is a green popup, the screen gets very busy really fast.

In Windows 95 you have no control how the user got there, wherever there is.

Ways to get there include:

• Context sensitive help
• Browse sequence
• Jump from another topic
• Index

Since the user can get there from many places, you must provide them with everything they need to accomplish the task they are trying to get help with. This includes how to get to where they need to be to do what they are trying to do.

In the case of context sensitive help, remove the topics from the browse sequence and the index by removing all footnote codes except #. This allows you to know they didn´t get there from some other means and you can provide only the information you know the user needs right then.

top

How it Should Look

The screen is much harder to read than a page. Use lots of white space to make it as easy as possible for your reader. Use a sans serif font like Arial to make it easier to read.

Left justify text so that the eye can naturally move across the screen. Use a 8 to 9 point sans serif font for body font and 10 to 12 point sans serif font for headings.

Limit bolds and italics. They are really hard to read in the screen, especially italics. The screen makes italics look like this. Imagine reading an entire screen this way. Neither can your user.

top

What Should be There

Pictures and graphics

Using screen captures in a help system seem like the greatest idea in the world, but for most systems and most users, it is a bad idea.

The thing to remember about help is that user only goes to it as a last resort, when fiddling with the program has not helped them. After they actually open help, you have about 20 seconds to help them get the info they want. And they don't scroll nor do they logically analyze what to click. See the STC Journal for May 1998, I think, for an amazing article about testing users on help. The subjects were told that they were there to test the help and they still strongly resisted opening and using it. The results were everything I have observed informally over the years.

MS has also done a ton of research that wound up in the MS Windows 95 Help Authoring Kit book that has a chapter about designing help and what their studies show. What their studies show was that users don't know that they should click on a graphic picture of where they are. They think it is a picture of where they are. They don't click it.

So what you have is a tense and hostile user who didn't want to open help in the first place, will take about 20 seconds to see if there is something on the screen that can help them, won't scroll, even if the help topic obviously needs to be scrolled, and randomly clicks things if they figure out clicking things. They generally don't figure out that they can bookmark, print, or anything else. They just don't. They didn't even want to be in help to start with, why would they learn that they can print in a place they didn't want to open in the first place?

Showing them a big graphic of the screen they are on will take up real estate that they won't scroll past and they won't click on it to see your popups. They look at the screen shot and say "yes, that is where I am! But now what do I do?" Then they close the help and call customer support for the stupid product. (Not that your product is stupid but that is what the user thinks at that point cause no one wants to think that they are not getting something).

Task Oriented

What users want to know is ``How do I complete this task?" That is how they look up info and is what they want to see on the screen when they finally open help. Providing help that is oriented towards a 20 second attention span that won't click or scroll is your challenge.

Your help should include lots of steps to do stuff. Number the steps and keep the steps to 5 to 7 steps. If you make it more than that, people cannot remember it and they think the procedure is hard. And then they call customer support for help with this hard thing they want to do. If the procedure really is more steps, break it into chunks and then have the steps in the chunks be 5 or so steps.

Dialog Box Level Help

If the topic is opened from a dialog box, then tell the user what all that stuff is. That is what they want to know. They are in the middle of a task and know the how and why, they are confused about the stuff on the screen. They want to know what something is. Tell them. They can find it and then get back to work. Happy users are happy people.

top

Index

If your user figures out how to use the index, this is how the user finds what they are looking for. So index, index, index. Spend about 15% of the total development time creating the index. Be complete and use lots of variants on the terms in your product. Use gerunds (-ing words) and plurals. For example: printing files and then files, printing.

The Microsoft standard for indexes is lower case. It is easier on the eyes to have the index in lower case. It is the sign of a professional index. Remember to make all proper nouns upper case.

top

 © 2000 Anthrobytes Consulting   Hosted by PageWeavers.com
All trademarks belong to their respective owners.
All opinions expressed are just that, opinions.
Last modified Wednesday, 09 May, 2001.

Contact us at winhelp@winhelp.net