Three-Step plan for creating world-class Help systems

By Alison Reeves, Plain Words Help consultant

You know what you want to do. Now all you need to do is to get it done!

Here are the three steps that will lead you to a world-class Help system.

Step 1: Gather Information

1. Assemble functional specs, business specs, and any other documents created when the software was designed.
2. Identify a contact for: how the software is structured, how it works, and what its features and benefits are (this may be more than one person, e.g. programmer, sales and marketing etc).
3. Arrange a demonstration of the software by someone who knows it.
4. Find out if the Help has to be translated - this can affect the writing style because, if it is translated, it is important to be as concise and clear as possible.

Step 2: Create the Prototype Help

1. Decide on a structure, for example:
   1. Introduction
   2. Features and Benefits
   3. Screen Descriptions
   4. Task based topics (i.e. How To ... ... ...)
   5. Reports and Printouts
   6. Troubleshooting and Error Messages
2. Decide if the Help will be context-sensitive and to what level (i.e. screen level or field level).
3. Decide on the output - WinHelp, HTML, WebHelp. This should be done in conjunction with the programmer as it will be decided by the platform the software runs on, the language used for programming, and how much time the programmer can devote to programming links into the Help.
4. Agree the 'look and feel' of the finished product, including colours and styles.
5. Create a Prototype that includes all the Help topics and send this to your contact for approval before inserting all the text. Also, include a list of assumptions so that you are both clear what is expected.
6. Review feedback from the Prototype and make any adjustments.

Step 3: Create the Help

1. Write up the topics.
2. Create links between topics, especially screen descriptions and task-based topics, as you go along so you don't miss any.
3. Check your writing style is active, and, if the Help is to be translated, that it is concise.
4. Get an independent QA

Alison Reeves
Plain Words eLetter
January 2004