Creating Effective JavaHelp

Chapter 4. Preparing Help Topics

The two most important features of any online documentation system are well-written, meaningful topics and a good navigation facility. This chapter discusses the former.

JavaHelp topics are written in HTML. This chapter doesn’t teach you HTML, but it explains how to apply HTML to certain parts of JavaHelp topics. If you are not familiar with HTML, you may want to consult O’Reilly’s HTML: The Definitive Guide.

While most of the concepts in this chapter apply to all online documentation systems, I discuss them as they apply to JavaHelp. To help you create well-written and meaningful JavaHelp topics, this chapter provides the following guidelines for accomplishing the following tasks:

• Planning your help topics

• Creating help topics and applying appropriate HTML tags

• Writing effective and meaningful help topics

• Using preexisting HTML topic files

Planning Your Help Topics

In the previous chapter I outlined the entire JavaHelp project. I also explained that you should determine general help-topic areas based on your research of the audience and their needs. In this section I examine the following basic tasks that break down the general topic subject areas into specific online help topics:

• Assigning work to help authors

• Organizing information into help topics

• Obtaining approval from team members

Assigning Work to Help Authors

If you are working with a team of help authors, there are various methods for dividing the work among the team members. One method is to make each help author responsible for a different type of topic. For example, if three help authors were working on a project, one could work on field-level help, another on conceptual help, and the other on procedural help.

If the help authors have limited time for learning the application for which they are writing online help, you might try another method, in which each writer works in a specific subject area (such as creating new documents or formatting text). This method has each writer creating topics of all types (field-level, conceptual, and procedural) for his or her assigned subject area. The benefit to this approach is that each author spends time learning only a small portion of the application.

For large projects, you should assign the help-topic types (field-level, conceptual, procedural, etc.) to teams. Then have each team allocate help topics to the individual help authors. For example, if a team of help authors is working on field-level help, have each author work on the topics for different screens. Then, you won’t have help authors duplicating efforts, and each author can remain focused on a specific type of help topic. Again, depending on your resources, you might have help authors focus on particular subject areas instead of topic types, to minimize the time required for learning the subject matter.

If you are working alone on the project, it’s still wise to think of the different topic types and subject areas as separate components. Although you are responsible for everything, breaking things down can help you approach the project in an organized manner.

Organizing Information into Help Topics

Once you know the specific topic types and subject areas for which you are responsible, you can begin organizing specific information into individual help topics—a process known as chunking . For example, if you want to create procedural help that explains how to use the word processor’s formatting tools, first determine specific procedures, such as how to embolden text, how to italicize text, and how to color text. You then place each of these procedures in a separate help topic instead of combining them in one long topic.

At this point in the project you should have an idea of the information the help topics will contain, so you can give each topic a title. Keep your project organized as you create the topic titles. In the last chapter, I used the word processor-application example to show how to organize the general help types and subject areas into a directory and file structure. When you decide on the topic titles, start creating the actual files within your directory structure. You won’t write the topic content yet, but you can accomplish two tasks at once if you create the topic’s HTML file at the same time you outline your topics and create topic titles. For example, you can create actual HTML files for the help topics on emboldening, italicizing, and coloring text. You aren’t yet ready to write the actual content or procedures within the help topics, but you can determine their titles based on the information the topics provide. Later, when you write the content of each help topic, you can simply use the appropriate HTML file you have already created.

Based on the word processor example, Figure 4.1 shows how you might set up a directory and file structure for help topics on formatting text.

Figure 4-1. Organizing help topic files

When I outline topics for a new help project, I usually create and categorize the topic files with their actual topic titles as shown in Figure 4.1. Then, when I want to print out or show someone my outline, I simply take screen shots of the directory and file structure and use them as my printed outline.

Later in this chapter I provide some tips on chunking the individual help topics, designing topic titles, and naming topic files.

Obtaining Approval from Team Members

When you have determined the specific help topics you will prepare, you should present them to other members of your development team to get general approval. Depending on your company, this approval could be a verbal “sounds good to us,” or it could be a formal proposal, requiring signatures from team members, verifying that your help topics are appropriate for the project. Make sure that everyone agrees that the topics you have outlined can be prepared by the project deadline.

If you present the report to managers, or if you are working under particular deadlines, you should include anticipated completion dates to show that you can complete the help topics in time for the project deadline. In Chapter 3, I discussed determining the time required for you to create help topics.