Help Should Be Helpful

Let's start by understanding the true goal of documentation. After all, users don't like reading documentation, and we certainly don't like writing it. So why bother? Users need documentation to help them get their work done. Although users don't read it unless they have to, when they do read it they want it to answer their questions. If it doesn't answer their questions, they're not happy.

Software developers want good documentation because they want happy users and they want to have small technical support departments. Bad documentation means a lot of technical support calls. To minimize technical support calls, you need to address documentation issues in the following order:

• Improve the software Your first choice should always be to improve the software so that documentation isn't required.
• Add to the documentation If improving the software can't solve the problem, you need to document the problem for the user.
• Add to the readme file The readme file is your last defense against a technical support call.

However, the above goals can be consolidated into a single, simple goal. The ultimate goal of Help and documentation is summed up by this tip:

TIP

---

Help should be helpful.

This goal would go without saying were it not for the fact that much Help out there isn't helpful! Software documentation sometimes looks as if it has been written by someone who understands Microsoft Windows but who knows nothing about the particular program. And sometimes it looks as if it has been developed with little thought, simply as an obligation that nobody really cares about.

And what is helpful? Let's start by first looking at what isn't helpful:

• Giving basic information on how to use Windows Your Help shouldn't spend time explaining how to use the mouse, what a menu is, how to select items in lists, how to double-click, and so on. If your users are beginners, you might want to refer them to the Help that comes with Windows or the appropriate sections in the Windows user's manual, Getting Started with Windows 98.
• Describing the screen, menus, or toolbar The user already knows what the screen, menus, or toolbar looks like. Generally, such descriptive Help isn't helpful.
• Covering what is obvious by looking at the screen Nothing makes me want to scream more than asking for help and being told what should be obvious to a complete idiot.
• Providing a tutorial that teaches a procedure without explaining the significance of its action Tutorials that show how to select various menus, dialog boxes, controls, and so on but don't say why you'd want to do this teach little.

Given what isn't helpful, what is? Whenever I use Help, I'm generally looking for the following Help topics that are helpful:

• Providing an overall description of the program and a quick tutorial if the software is complex and unfamiliar to me.
• Explaining how to perform specific tasks.
• Clarifying the significance of the choices in a dialog box.
• Telling me what to do when I receive an error message I don't understand.
• Providing tutorials that present information the way you would present it if you were training someone to use the program. You wouldn't train someone by saying "First click this button, and then click that button." Rather, you would explain what the feature does, when and why you would use it, and what the significance of the various options are.

If your documentation accomplishes all of the above, you're on the right track.