How to write a Help file

How to write a Help file – what advice you you give to someone who was looking to write a Help file for the first time?



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”.


Some great info from mjb.

A few things I can add…

Try to get your help into the UI
I think the most effective software is that were the user doesn’t have to consciously duck into a Help system. If the software UI allows for you to embed helpful text in the screens and on popups, I recommend doing that.

Consider an FAQ
I am recently becoming very taken with the ideas of FAQs and how they can serve as a ‘door’ to the Help system. I’ve seen FAQs used well on web sites, and I can imagine similar software UIs also having such FAQs that, where necessary, link to the relevant procedural topics.

Terminolgy and feature/UI complete
I think two of the things that can drastically affect the author’s chance of producing a good Help system is if the product terminology is inconsistent or unclear, and if the Developers keep altering the features and UI.
If you can get some stability in these areas, you’ll increase your chances of accomplishing your task.

Good luck!
James Lawrence.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.