No book can make you an expert on information design, and while the purpose of this book is to teach you how to develop JavaHelp projects, I also provide some tips in this section to help you prepare better JavaHelp topics:
Note
If you are already experienced with designing help topics, you might want to skip the rest of this chapter.
The best way to start this discussion is to explain the way users don’t read online help. They don’t read online help the way you are reading this book. With online help, the user doesn’t read the document from start to finish. There is neither a beginning nor an end to the document.
Generally, users enter a help system with a question for which they want an answer or a task for which they need instructions. Users are typically in the middle of working with the application and don’t want to spend time reading through a lot of information. They tend to skip over sections and skim through sections to find the specific information they need.
The troubling fact about online help is that you don’t have many chances to give users what they want. Typically, users will try only a few times to find the information they want before giving up on finding the topic. After several futile attempts with the same help system, users start to lose faith in the information the help system provides. If you don’t carefully craft the help topics, as well as the navigational facility that gets the users to the topics, you could very well waste time developing a help system that no one uses. The solution, however, is not to omit the help system, afraid of wasting valuable time. Instead, the solution is to take the time to create well-written and meaningful help topics through which users can find the information they need.
As mentioned earlier in this chapter, when you chunk information, you are breaking it down into separate topics so that each chunk of information treats only one subject. For examples of chunking, look through this book. You’ll see that information is chunked into sections within each chapter. The previous section provided information about how users read online help. This section provides information primarily about chunking.
You must be more specific when chunking information for online help than for hardcopy documents. Using the word-processor example, it’s not enough to provide one topic on formatting text. Instead, you need one topic that lists the types of formatting options, one topic that describes how to use bolding, one topic that explains how to use italics, and as many other topics as needed to cover all formatting options.
Thus, Figure 4.2 may not be a good model to follow for designing a help topic. While the entire help topic discusses only text formatting, it presents multiple topic types and attempts to answer more than one question. It provides concepts on the word processor’s text-formatting options and also gives procedures for formatting the text. A good help system would have the conceptual information in one topic and the procedural information in another.
After you have chunked information into separate subjects, you can begin writing the topic content. Approach writing each topic as an individual document. Never assume the user has read any other help topic prior to the one you are writing. This approach means you can’t assume users have any previous knowledge of the subject. Good information chunking keeps you from writing topics that require prerequisite information and therefore eliminates the tendency to write introductory material in every help topic.
Most online-help users skim through information instead of reading every word and sentence. To help accommodate users’ reading habits, you must write short, clear, concise sentences and use short paragraphs. You should also use small, simple words. As you write each sentence and are thinking about the right words to use, remember that one important JavaHelp navigation component, the word-search index, finds topics based on the words you use within the help topic. Users type a word, and the JavaHelp index presents a list of the help topics containing that word. Therefore, try to use words you anticipate someone will use in a word search.
In addition to sentence and word structure, consider the following tips while writing your help topics:
Avoid jargon and define all technical words and abbreviations. In Chapter 5, I discuss pop-up windows and show you how you can use them to define new words.
If you must write a long help topic, break the topic into subheadings. Since users scan through the help topic, subheadings help them locate particular sections.
Don’t avoid writing a help topic because the subject is too confusing. Spend the time to make the subject clear and easy to understand. If a procedure in the application is difficult to document, it is probably difficult to perform. You should look at such procedures to see if you should change the actual application interface to make it easier for users.
This tip may seem like a lot of additional work, but your users will appreciate it. The documentation phase presents an excellent opportunity to test the application’s interface. Take advantage of it. Instead of trying to cover up interface flaws with awkward documentation, fix the interface so that both the application and its documentation will be friendlier to your users.
Be consistent with your writing style and choice of words. If you refer to the software application as the “system,” use this word consistently. Don’t use “system” in one place, “application” in another, and “software” in another. The user will waste time trying to find the difference in meaning among these words when in fact you use them all to mean the same thing.
Place cautions and important notes before the passage they modify. For example, if you want to tell the users that performing Step 3 will delete the contents on their hard drive, tell them before they read Step 3. Don’t wait until after the user performs the action. This tip might sound obvious, but many writers place cautions like this one at the bottom of the topic or after the particular step. People won’t read everything before performing a step, so make sure they know important consequences before they take action.
Limit procedures to no more than seven steps, because users can process only about three to seven online items. If you must use more then seven steps, try breaking the procedure into multiple procedures. However, sometimes breaking procedures apart just to avoid using more than seven steps is not feasible. You are better off giving the user nine steps for a task than creating multiple procedures and making users jump through the help system to finish the task.
Avoid using the future tense by eliminating the word “will.” For example, don’t say, “When you select the formatting option, the system will display the formatting screen.” Instead say, “When you select the formatting option, the system displays the formatting screen.” Users are taking action in the present tense. Making a sentence future tense by using the word “will” not only is inconsistent with the user’s present action, but also makes sentences unnecessarily long and awkward.
Write in the active voice instead of the passive voice. When you write in the active voice, you make something take action on something else instead of the “something else” being acted upon. For example, if you say, “When you select the formatting option, the system displays the formatting screen,” you are using the active voice because the user takes action on the system, and the system takes action on the formatting screen. However, if you say, “The formatting screen is displayed when the formatting option is selected by the user,” you are using the passive voice because the formatting screen and the formatting option are being acted upon.
Another problem with using the passive voice is that it generally forces using a phrase such as “the user” as I did in the previous example. Since the users are the people for whom you are writing, write to them directly instead of writing about them. Use the word “you” as I did in the example of an active sentence instead of the phrase “the user” as I did in the example of a passive sentence.
When you are writing the help content, keep in mind the length of the help topic. There is no magical number of words per topic that will work best for your users. Setting such a number stops you from providing important information in an attempt to avoid writing longer topics. It also forces you to write longer topics in place of shorter ones just to fill up space. You must provide as much information as is required to discuss only the given subject—nothing more, nothing less.
Take a common-sense approach to setting topic length. When was the last time you enjoyed reading a lengthy topic while trying to operate a software application? Your users are most likely no different from you when it comes to reading software documentation. Give them only the information they are looking for. If doing so means writing a longer topic, your users will probably be happy that all the information they want is there. Remember, though, to break down longer help topics into subsections with their own subheadings.
Once you have written the topic’s content, you must give the topic a title. Users should know simply by reading its title if they want to read a help topic. The topic title should tell users whether or not the help topic contains the answer to their question. For example, “Applying Bold Formatting to Text” says more to the user than “Bold Formatting.”
In designing a topic title, be sure to use a short phrase that concisely describes the topic’s contents. Like the topic itself, topic titles should be self-contained. Don’t make a help topic title depend on text or titles from other topics. Users will see this title in JavaHelp’s table of contents and must decide from there what the topic title means.
As
discussed in Chapter 1,
the word-search index uses the information you place in the
<title> tags of your help-topic files. Also,
in JavaHelp 1.1 and later, the titlebar of a secondary window
displays the text of its topic file’s
<title> element. For this reason, you should
use the topic title you specified in the TOC file in your help
files’ <title> tags. For our
word-processing help example, you would use the following line in the
topic file to specify its
title:
<title>Formatting text</title>
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.
