Help files are an essential component of all types of software, from word processors to FTP programs. Although the types of topics you will address in your help files will vary depending on the software, these general rules apply to all types of help files:
Don't assume prior knowledge: One of the most important things to keep in mind while developing help files is that software users may not have any prior knowledge of the software or technology in general. If you're describing how to resize a table, don't automatically assume the user will know how to make a table. Write as though you're speaking to an absolute beginner.
The simpler, the better: The best help files are the ones that can break down tasks into clear and simple steps. If you're describing how to bold text, this can be broken down into two steps: Highlight the text you want to format. Click Bold. Resist the urge to add unnecessary description or use complex sentences.
Describe one task at a time: Even very simple tasks should be described separately. Develop separate explanations for how to save a file, how to create a new file, and how to open an existing file.
Develop clear titles that describe the task being explained: Tell users exactly what they are being taught how to do. Titles for spreadsheet help files might include "create a new spreadsheet," "add borders to cells," or "design a formula."
Use links if background information is required: In some cases, the user will have to complete one or more preliminary tasks before they can perform the operation being described in the help file. If you are discussing how to change a slide layout in a presentation program, the user will need to know how to create a presentation, how to add slides, and how to add text and graphics to slides. At the end of your explanation, you can include links to these topics in case the user has to refer to them.
Make use of screen shots when appropriate: Screen shots are very effective tools when developing help files, particularly when you are describing a process that consists of several steps. Use screen shots to show users where they can find the toolbar icons you are referring to. Screen shots are also useful because they show users what they should be seeing on their computer screens. This will tell them whether they are completing the process correctly.
Quick tip: Remember, the purpose of help files is to explain tasks as clearly as possible. Don't worry about showing off your writing skills or being creative. You might end up writing at a grade-one level, but users who are unfamiliar with the software will appreciate your straightforward approach.
Last Updated: 05/05/2014