The Author's Job

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 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 HP VUE Help Manager), making the information more widely accessible. If another help volume contains hyperlinks to topics in your help volume, your help volume must be registered.

Stand-Alone Help Volumes.  If you are writing a stand-alone help volume (a help volume not associated with an application) you may choose to do things very 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 via at least one hyperlink. Also, because there's no application associated with your help, you must rely on a help viewer (such as Helpview) to display your help volume.

Collaborate with the application programmer

If you are writing application help, you should work closely with the application programmer. The degree to which the HP 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.

Organize and write your topics

The HP Help System best supports a hierarchical organization of topics. This familiar way of organizing information helps users know where they are when viewing a particular topic.

The General Help Dialog provided by HP Help includes a "Topic Hierarchy" list that indicates the path from the home topic (at the top of the hierarchy) to the current topic. Essentially, this is "you are here" information for the user.

Although HP Help has been optimized for information that is organized in a hierarchy, you are free to create any kind of organization you want. The Quick Help Dialog is a simpler help window that does not include the Topic Hierarchy. In this window you can present topics that are not organized in a hierarchy. Using hyperlinks you can connect related topics organized in any way you want, including "webs," "chains," and "loops."

Writing with HelpTag.  Online help is written in ordinary text files. You use special codes, or tags, to markup elements within the information. The tags form a markup language called HP HelpTag.

The HelpTag markup language defines a hierarchy of elements that define high-level elements such as chapters, sections, and subsections, and low-level elements such as paragraphs, lists, and emphasized words.

“General Markup Guidelines” describes the details of using markup. Chapter 11 “HelpTag Markup Reference” includes a description of each element and the tags needed to enter it.

Think structure, not format.  If you are familiar with other publishing systems, you may be accustomed to formatting information as you like to see it. Authoring with HelpTag requires you to think about structure and content, not format.

As you write, you use tags to mark certain types of information. When you do so, you are identifying what the information is, but not how it should be formatted.

For instance, to refer to a book title, include markup like this:

   <book>OSF/Motif Style Guide<book>

This abstraction separates structure and content from format which allows the same information to be used by other systems and perhaps formatted differently. For instance, HP Help displays book titles using an italic font. However, on another system an italic font may not be available, so the formatter could decide that book titles are underlined.

Create run-time help files

The text files you write must be "compiled" using the HelpTag software to create run-time help files. It's the run-time help files that are accessed when the user requests help.

Review help as the user will see it

During the authoring process you will need to display your help so you can interact with it just as your audience will. There are two ways to do this: