Common Desktop Environment: Help System Author's and Programmer's Guide

The Author's Job

Writing online help differs from writing printed manuals, so it is important to understand who you are writing for, how the information is accessed, and how the information fits into an application.

Objectives for Online Help

The two most important objectives for designing quality online help are:

Applying these objectives will help you make decisions regarding what type of help is best and what amount of detail is needed.

Know Your Audience

Just as with any writing, to do a good job, you must know your audience and understand what they require from the information you are writing. Most importantly, with online help, you need to know the tasks they are attempting and the problems they may encounter.

Consider How Your Help Is Accessed

It is just as important to understand how users will access your help as it is to identify your audience correctly.

Application Help

If you are writing help for an application, you need to decide which topics are browsable and which topics are available from the application as context-sensitive help. A topic is browsable if you can navigate to it using the topic tree or hyperlinks. Topics designed exclusively for context-sensitive help might not be browsable because the only way to display the topic may be from within a particular context in the application.

You must also decide if you want your application's help volume to be registered. Registered help volumes can be displayed by other applications (such as the Help Viewer), making the information more widely accessible. If another help volume contains hyperlinks to topics in your help volume, your help volume must be registered.

See "Registering Your Application and Its Help" for information about installing and registering your application.

Standalone Help Volumes

If you are writing a standalone help volume (a help volume not associated with an application), you may choose to do things differently.

First, you must provide a path for users to get to all the topics you've written. That is, every topic must be browsable through at least one hyperlink. Also, because there's no application associated with your help, you must rely on a help viewer (such as Help Viewer) to display your help volume.

Evaluate How to Present Help

An application can incorporate different types of help. It is important to evaluate what kind of help is best suited for your application. For example, the same help information may be presented in a variety of ways. Some choices include key features, a tutorial, examples, task instructions, shortcuts, troubleshooting, reference information, glossary of terms, or referral to hard copy or other online documentation. A help volume often combines different presentations.

Collaborate with the Application Programmer

If you are writing application help, you should work closely with the application programmer. The degree to which the Help System is integrated into an application is a design decision that you make collectively.

If an application and its help have very loose ties, there may be only a handful of topics that the application is able to display directly. This is easier to implement.

In contrast, the application could provide specific help for nearly every situation in the application. This requires more work, but benefits the user if done well.

It's up to you and your project team to determine the right level of help integration for your project.