Home > Support > Tips for Writing a Help System

If you have been tasked with writing a help system for your product, but you haven’t created a help system before and you’re not sure where to start, then this article is for you. Many software development companies can’t justify the cost of a hiring a fulltime technical writer, or simply don’t see the need for it. This article is targeted to the non-technical writer that has little experience writing help, or is writing a help system for the first time. The information in this article assumes that you are creating help for a software application, however could be used as a reference for creating help for hardware products, instruction guides, Policy manuals, procedure guides, etc.

Planning Your Help System
User manuals and help systems have evolved over the past several years in a variety of ways. The concept of answering questions and providing step by step instructions hasn’t changed, but there are several things to consider when writing a help system.

First, decide what formats the help system should be published to. These might include a ‘PDF Manual’, ‘web help’, ‘mobile help’, etc. If you’re not sure what format is appropriate, I would suggest publishing a web-based help system which can be either distributed with your product, or included on your company website. Some other questions to ask before designing your help system are:
- Do you have existing content that you want to import? If so, make sure that your help authoring tool can import documents such as MS Word, HTML, etc.
- Do you want to translate the help system to one or more different languages? If so, make sure that your help authoring tool can support the languages that you want to translate to.
- Will there be one help system, or multiple. For example: Getting started guide, Installation guide, Admin guide, user guide, FAQs, etc.
If you haven’t chosen a help authoring tool yet, take a look at HelpConsole 2010 (http://www.extremeease.com/helpconsole_2010_overview.htm).

Dynamic or Static?
In the old days, you would have written your help manual in conjunction with the development of your product, and then when the product was released, a physical user manual was shipped with your product. These days, help systems are more dynamic and are very often hosted on your website as opposed to being shipped with your product. The biggest advantage of hosting the help system on your website is that you can update your help content in one place, without having to push updates out to your customers. Here are some questions to ask:
- Will the help system will be bundled with your application, either as a physical manual, or bundled with the software?
- Will the help system be hosted on your website in a dynamic/editable format, where updates can be made as needed.
- Collaboration. Will there be more than one person adding help content to your help project? Does your help authoring tool allow collaboration from multiple locations?
- Do you want readers to be able to submit comments? If so, ensure that your help authoring tool allows reader feedback.

Build the Table of Contents
Plan and build the table of contents before writing your documentation. Try to structure it so that users will find it easy to navigate. Avoid burying help pages too deep or users won’t find them. After building the table of contents, add keywords to each page to build the index. The index will be included in the published help system, and will also be included at the bottom of the published PDF manual.

Include a ‘Getting Started’ Checklist
I recommend including a ‘Getting Started’ section that provides information about installing and configuring your product, and also provides details about key features of your product. This might also include a checklist of things that should be done to get up and running with your product.

Fully Understand your Product
Before writing the help system, make sure that you have a full understanding of how the product works and all of the features included. This may seem obvious, but if you’re writing help and only have a basic understanding of the functionality, you may exclude important functionality that the product provides. The tech writer at my previous company would sit down with a support rep and/or developer and walk through each screen before writing sections of the manual. This allowed the tech writer to ask questions about certain features and allowed the developer to point out important functionality that the tech writer may not have known about, or fully understood.

Brief & Easy to Read Topics
- Whenever possible, make your help documentation task orientated. For example, provide the specific steps required to add a new accounting record.
- Use consistent terminology. For example, if your help system referred to a field label as “label”, and then as “name” and then as “caption”, this may confuse the reader.
- When writing the help content, try to anticipate what questions users might have when running your application.
- Keep the help topics as short and concise as possible. Use easy to understand sentences and concepts as much as possible. Remember that the readers of your help system in most cases are using the help system as a last resort and as a reference when they don’t understand something or want more information about how a feature works. I’m sure that there are people who have read a help system from start to finish, but I personally don’t know anyone who has.

Include Screenshots and Videos
- Include many screenshots to illustrate the functionality that you’re documenting. If readers can see where the button is that they’re supposed to click, or the screen that they’re supposed to be on, there will be considerably less confusion, and fewer calls to your support department.
- Include flash videos. These may be as short as a few seconds or as long as a couple of minutes, but are invaluable for demonstrating how your product works. Videos can be easily created using a tool such as Camtasia (http://www.techsmith.com/camtasia)


Provide Feedback to Developers
- As you write the help system, provide feedback to the development team. If you personally found certain functions difficult to understand and explain when writing the documentation, then customers certainly will as well. Perhaps the user interface could be more intuitive or a brief description could be added to the form to explain what the user needs to do.
- Allow readers to add comments to the bottom of help pages?
- Provide an email link (or icon) within your help system to allow readers to submit suggestions directly to your development team.

Include a Troubleshooting Section
Include a ‘Troubleshooting’ or ‘Errors’ section in your help system. This will be very helpful when users encounter common error messages. If you are running a dynamic help system, you can add these errors to the help system as they are encountered. This will significantly reduce the number of emails and calls that your support team receives.

Written by:
James Dean,
Extreme Ease Software Inc.