Top five tips for producing powerful Help systems

Dr. Stephen King of Plain Words provides five "must-dos" for producing user-friendly Help systems that will bring an eerie silence to your technical support helplines.

Producing effective Help systems that are easy to understand and navigate is a tricky business. Done well, they will cut down calls to your customer support helplines and will create repeat customers.

Let's face it, there's nothing worse than not being able to use a piece of software to the full because you can make neither "head nor tail" of the Help. We've all experienced this, whether we are a technical wizard or a general business user.

Yes, the software product itself is priority No. 1, there's no escaping that, but scrimp on the Help and you will either limit your customer base to advanced, technical minded users; or your customer helplines will be swamped.

The answer is simple: you give your Help system the same priority as the software product.

Advertising literature, reviews, and e-mail shots will sell your product, but Help files are an equally important part of your marketing arsenal. If users can easily solve their problems by clicking on the Help buttons, they're going to feel good towards your product.

If they can't ... well ... they just get irate and red in the face. They might vent their anger on you with a stern letter or e-mail. That's the best scenario. The worst is they vent it on newsgroups and forums. Very bad public relations.

But if they have a happy experience using your Help system, they are likely to recommend your products on newsgroups and forums, which amounts to very good public relations and is likely to result in increased sales and good kudos in general.

What follows are five tips to set you on the road to creating a user-friendly Help system that will bring an eerie silence to your technical support helplines and keep customers coming back for more at every upgrade:

Tip one: Before you do a thing - decide what you want to produce

It's important to choose the most appropriate Help format for your application. It's also important to decide in the planning stage whether you are going to use any of the Help content to generate a User Guide or other type of document.

If you plan to Single Source, then you will have to bear in mind the different writing styles for Help vs. "printed" documentation and either insert additional content in the User Guide once it has been generated; or use Conditional Text to mark whether content will appear in the Help, User Guide, or both.

When choosing your Help format, you will probably need to decide between WinHelp (still popular), HTML Help or some form of Web-enabled Help (which is typically a set of uncompiled HTML files). If you are working with Java applications, you can also consider JavaHelp.

Plain Words can help you decide on the best format, go through the pros and cons of each type and also provide you with samples so that you can compare the different types of Help. Call 01635 202013 or email

Tip two: Decide which Help Authoring Tool you are going to use

Help Authoring Tools do just what the name suggests, they provide an environment and a set of tools which makes writing Help much easier. In short, you can concentrate on authoring content which increases your productivity and output. Each tool has its own quirks and limitations, and it's important that you are comfortable with the tool that you are going to use. You might even have some existing Help that you want to use and it's important that the tool you are going to use can import this material with the minimum of fuss.

Plain Words can help you decide on the best tool to meet your present and future requirements. Call 01635 202013 or email

Tip three: Get the structure right before you begin to author content

While there is nothing to stop you just wading in and starting to write, it's not recommended. You need to work to a plan and one of the best ways to do this is to create an empty Help skeleton. You'll save time when you create the Help pages if you also put in any index keywords. You also need to work out how to handle any context sensitivity and it's best to talk to developers at an early stage to work out how you are going to work together. Once you have the structure worked out you can plug the Help into the application and test that everything works as you expect.

Plain Words can help you design the structure of your Help and even create an empty shell into which you can author the content. Call 01635 202013 or email

Tip four: Working in a team environment? Work out how you are going to manage files

If you are going to have more than one author working on a particular Help Project, then you need to decide how the various files are going to be managed. If you are using Version Control Software, then it's best to nominate someone in the team as the owner of the key project files. It may be that your proposed Help structure falls nicely into several modules; each author can then work independently on a module and the whole Help can be put together later. There are a few things you need to get sorted if you are going to produce modular Help, to make sure the finished result is seamless, and users can't see the join! If you get all these sorted before you start, you can focus on writing rather than technicalities.

Plain Words can help you iron out any issues that you might have with managing files and work out procedures if you are working with other authors or need to check files in and out of a VCS. Call 01635 202013 or email

Tip five: Use templates, style sheets, and skins to ensure consistency and make it look good

Templates and style sheets will make the authoring job much easier and also ensure consistency across projects. If you are generating a document from the Help, it's worthwhile thinking about the Word template too. If you keep things relatively simple, then you'll avoid a lot of reworking at the end. Make sure that your Help looks good and is also easy to use; people will remember your Help system if it's visually appealing and works for the user.

Plain Words can help you design the look and feel of your Help system and also advise on the best way to generate documents. Call 01635 202013 or email

Dr Stephen King
Plain Words eLetter
January 2004