Before you start writing the text for your help topics, you should understand the concepts behind naming the topic’s HTML file, formatting text in the topic, and using links to different topics and web sites.
When you create your HTML files, consider the tips in this section for choosing meaningful filenames and keeping your project well organized. If you use consistent, logical filenames, you should be able to recognize the subject of the help topic just by looking at its filename.
When naming files, consider the following related HelpSet items:
Filenames
Map IDs
Topic titles
Name the help-topic files in such a manner that anyone can easily match them to their corresponding map ID and topic title. However, you don’t want to give the files ridiculously long names that become hard to manage. I tend to use nearly identical names for all three related items. So, for a word-processor help topic on formatting text, I would use the map ID “FormattingText,” the filename “FormattingText.htm,” and the topic title “Formatting Text.”
Note
If you use a third-party help-authoring tool to create your HelpSet, you may not have a choice in assigning the map ID: the third-party tool may automatically create it. However, third-party tools that automatically assign the map ID typically allow you to work at the topic-title level, so that you don’t have to pay attention to map IDs.
Before writing text for your help topics, you should know how to use HTML formatting tags in JavaHelp topics. As you write each topic, you will want to apply formatting tags to the topic title heading, subheadings, body text, bulleted lists, and numbered lists.
In Chapter 2, you used HTML tags to format text within help topics. You probably remember that it was as simple as writing a basic web page, since the HelpSet Viewer is based on HTML. Now take a closer look at applying available formatting tags to JavaHelp topics. Figure 4.2 shows the HelpSet Viewer with a help topic that contains a variety of text formatting.
Here is the source text for the topic shown in Figure 4.2; it uses standard HTML formatting tags:
<html>
<head>
<title>Formatting Text</title>
</head>
<body>
<h1>Formatting Text</h1>
<p>You can use the following text formats with the word processor:
<ul>
<li><strong>bold</strong></li>
<li><em>italic</em></li>
<li><u>underlined</u> </li>
</ul>
<p>Use the following steps to apply text formats:
<ol>
<li>Highlight the text that you want to format.</li>
<li>Click <strong>Format</strong> from the <strong>Edit</strong> menu.</li>
<li>When the <strong>Format</strong> window appears, click the appropriate
text format.</li>
<li>Click <strong>OK</strong>.</li>
</ol>
</body>
</html>This text uses the following HTML formatting tags:
At the time of this writing, the HelpSet Viewer doesn’t support the following HTML tags or attributes:
You should refer to JavaHelp’s documentation or Sun’s web site for ongoing updates to this information.
Keep in mind that you should not use a lot of text formatting in the same help topic just because you can. Too much formatting can be a strain on the reader’s eyes. Reserve text formats such as bold, italics, underlines, and color for special conditions. These text formats will be more effective if you use them sparingly.
As you create your help topics, you should consider how topics relate to one another. You might have a help topic that explains the basic concepts behind using word-processor templates and another topic that provides step-by-step procedures for using templates, but the user might not know that both of these topics exist.
You can help the user locate related topics by using HTML hyperlinks. You created a hyperlink in Chapter 2 that enabled the user to click selected text and jump to the related help topic. Creating a hyperlink is easy; you use HTML code within your help topic as demonstrated in the following example:
This online help system also provides conceptual information on <a href="../UsingTemplates.htm">using templates</a>.
In this example, <a href="../UsingTemplates.htm"> sets up the hyperlink so
that the user can simply click the text “using templates”
to jump to the related topic.
When using this kind of link, be careful selecting text to which you apply the hyperlink; you don’t want to select more text than necessary. In the previous example I applied the link only to “using templates” instead of to the entire phrase “conceptual information on using templates.” The latter would have disturbed the smooth flow for readers not interested in the hyperlink.
Don’t use too many hyperlinks in one help topic. By following too many hyperlinks, users risk getting lost in your help system and may become frustrated enough to stop using it. Also, make sure the hyperlink actually links to a topic that expands on the subject. I have seen many cases where authors include hyperlinks that send the user to another topic, only for the user to find that the new topic doesn’t actually provide additional information on the subject.
Another way to help your users is to have a “Related Topics” or “See Also” section at the bottom of the help topic. This section provides a list of other topics in the current HelpSet (or in a wider scope) that are related to the topic the user is currently reading. To make effective use of related topics, make a note of which help topics closely relate to others while you are organizing and writing the help topics.
Your audience uses related topics in a different manner than they use other hyperlinks. They turn to related topics specifically to see what other help topics exist that might help them find more information on the current topic. Since you don’t force the related topics feature on users (you place it at the bottom of the help topic) you can include all topics that relate to the current one—even if you already included the topic earlier in a hyperlink.
Get Creating Effective JavaHelp now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
