How to write a Help file

Your goal should be to write online help that is helpful. To do this, you must know the users, anticipate their questions, and answer their questions directly and with respect.

Who is going to read the help?
If you know the audience characteristics, you are part way to creating effective information. Write at the proper level for that audience, use consistent terminology, use the active voice, and conform to your company’s style guide.

Why would anyone come to a particular help page?
Obviously the reader consulting online help wants to solve a problem–but can you know beforehand what their problems will be? With software, a common problem is “grayed-out” functions. For example, I see that my graphics program supports anti-aliasing, but it doesn’t work for my current graphic. In your online help you would want to explain that anti-aliasing requires a particular ‘depth’ of color and how to enable this for a graphic. Another common problem is terminology: if your firm is introducing a product into a market where there is an established leader, you will want to ensure that there ia a mapping between their terminology (say, “bookmarks”) and your company’s terminology (“favorites”) so that customers can migrate to your software comfortably. If the software you are documenting already has a customer base, talk to your Support people to ensure that the questions they hear most often are covered in your online help.

What does it mean to ask for help?
In the context of trying to use software, very often it means that the reader is frustrated. They want to perform a task and they believe it should be obvious and they cannot do it. Your online help has to be clear, concise, and supportive. That is, you do not say, “Simply do X then do Y.” Allow the reader to decide in hindsight that doing X then Y was simple, but do not make the reader feel incompetent for requiring help to be able to
perform a task that you feel is “simple”.