Creating Effective JavaHelp

Content preview·Buy reprint rights for this chapter

When I first saw a demonstration of Sun Microsystems' JavaHelp early in 1998, I knew that Sun had designed a great new HTML-based help system that would answer most help authors' needs. They proposed the best online help solution for Java applications and applets, and offered a great source for online help and documentation in general. Finally: online documentation that is easy to author, easy to use, and, best of all, fully functional across all computer platforms.

We are entering an age in software documentation where new HTML-based help systems are emerging and are trying to provide solutions for all help-authoring needs. With Java becoming such a widely used programming language, help authors need an HTML-based help system that is as flexible as the Java applications themselves. JavaHelp to the rescue!

To get you started learning JavaHelp, this chapter provides the following topics:

What is JavaHelp?
Using JavaHelp for online documentation
Understanding the files in a HelpSet
Following the JavaHelp process
Installing JavaHelp on your computer
Seeing JavaHelp in action
Deciding how to present a HelpSet
Deciding how to install a HelpSet
Encapsulating HelpSet files
Finding more information on JavaHelp

JavaHelp is an online help system developed in the Java programming language. It is similar to other help systems, such as WinHelp and HTML Help, in that you use a table of contents (TOC), index, or word-search index to find and display help topics. A complete "online help data set," consisting of individual help-topic files, TOC, and indexes, is called a HelpSet .

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

JavaHelp is an online help system developed in the Java programming language. It is similar to other help systems, such as WinHelp and HTML Help, in that you use a table of contents (TOC), index, or word-search index to find and display help topics. A complete "online help data set," consisting of individual help-topic files, TOC, and indexes, is called a HelpSet .

As shown in Figure 1.1, JavaHelp uses a tripane window (a window with three frames), which contains a Toolbar pane, a Navigation pane, and a Content pane. This tripane window, called the HelpSet Viewer, offers users the ability to work with the help system's commands, navigation controls, and help topics at the same time, without having to switch to different windows. Using this tripane window, users select an item from the navigation pane, and the corresponding help topic appears in the content pane. If a help topic contains a link, the user can click it to display the corresponding HTML page in the content pane. If the link leads to another topic in the same HelpSet, the navigation pane automatically updates itself to highlight the title of the new topic.

Figure 1.1: The HelpSet Viewer

The HelpSet Viewer functions like a web browser: it has similar controls, but it is designed specifically to work with JavaHelp files.

JavaHelp topic files are HTML files, and these HTML files function the same way as in a web browser. The HelpSet Viewer also supports pop-up windows, secondary windows, and multimedia clips. (Java programming is required to provide a Java multimedia component for use with the HelpSet Viewer.)

Like other help systems, JavaHelp can present help information to users in several ways:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

With so many options for online help systems, you may wonder why you should use JavaHelp or how it compares with other online help systems. JavaHelp may be not only the best online help system to use with your Java applications or applets but also a great source for providing online documentation in general.

If you are designing online help for a Java application, JavaHelp is the best help system for the job. Since JavaHelp is written in Java, it is platform-independent and guaranteed to run in any environment in which its associated Java application runs. Also, since JavaHelp is implemented using Java Foundation Class (JFC) components, Java programming can customize JavaHelp's interfaces and functionality.

JavaHelp offers many online help-presentation options. You can design it for standalone, context-sensitive, or embedded modes; you can also use other standard help features such as pop-up windows, secondary windows, and multimedia integration.

Finally, JavaHelp is easy to merge and update. If you have different software applications with different HelpSets, you can merge them so that users see a single, integrated online help system. If you ever have to update your JavaHelp topics, you can easily do so since JavaHelp uses standard HTML files for its help topics.

Help authors today have many options for providing online documentation. Most help authors are familiar with WinHelp, an older Windows help system that provides online documentation with Windows-based applications. Today there are an increasing number of online help options, most of which are based on HTML. HTML-based help systems (such as JavaHelp) offer online help solutions for more than just the Windows operating system.

Having many online help systems to choose from, however, makes it more confusing for help authors to decide which help system to use under which situation. It is not the position of this book to tell you which help system to use in different situations—only to help you recognize circumstances for which JavaHelp is your best online help solution.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Each online help project (such as the Aviation project previously illustrated) is implemented as a set of files, called the HelpSet . A HelpSet includes HTML-format topic files along with JavaHelp-specific configuration files.

The HelpSet includes three kinds of files:

HelpSet data files
Navigation files
Topic files

HelpSet data files contain overall information about the structure and content of the HelpSet. These are text files, structured in Extensible Markup Language (XML) format. There are two HelpSet data files:

The HelpSet file, with filename suffix .hs, is the HelpSet's "master control" file. It specifies the navigation components to be used, along with the files that configure the navigation components. It also specifies the HelpSet's map file.

Don't confuse the similar terms HelpSet file and HelpSet. The HelpSet is the set of all files in a particular project; the HelpSet file is the project's master control file.
The map file, with filename suffix .jhm, assigns a map ID (shorthand name) to each help topic. It maps ID strings to the uniform resource locators (URLs) of topic files. The HelpSet file and navigation files always use map IDs to refer to help topics; they never use the topic's URLs directly.

The navigation files configure the HelpSet's TOC, index, and word-search index. The TOC and index files (also in XML format) are similar in structure. The JavaHelp system reads the information in these files to know what to display in the TOC and index tabs in the navigation pane.

What is the difference between "JavaHelp system" and "HelpSet"? I use the term JavaHelp system to mean the HelpSet Viewer (or a viewer embedded in another application) in action: loading a HelpSet, displaying its help topics and enabling the user to navigate between topics. The term HelpSet is just the set of files

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The JavaHelp system begins by reading a HelpSet file, which provides information about a particular help project. To display navigation information, the JavaHelp system reads the navigation files listed in the HelpSet file. Additionally, the JavaHelp system uses the information in the map file to find the individual topic files in the HelpSet. Figure 1.2 demonstrates how the HelpSet files work together to display information in the viewer.

Figure 1.2: How a HelpSet's files work together

For example, let's say that a person accesses online help to find a help topic on deleting files in an application. When the user opens the HelpSet for that application, the system first reads the HelpSet file and determines the location of the map file and the navigation files. The system then reads those map and navigation files and displays the navigation information in the navigation area of the HelpSet Viewer. The user can then use the navigation components (TOC, index, or word-search index) to find the topic on deleting files. The appropriate help topic then displays in the content area of the HelpSet Viewer.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

To work with JavaHelp while you read this book, you must set up your computer to run JavaHelp as well as the sample files in this book. You can obtain the JavaHelp distribution from Sun Microsystems' JavaHelp web page at http://www.java.sun.com/products/javahelp. Also, I provide a link to Sun's download page under "Examples" on the book's web page, http://www.oreilly.com/catalog/creatingjavahelp.

Once you connect to the download site, Sun provides instructions on how to download and run the JavaHelp installation file. Although Sun provides a default installation location, I installed JavaHelp to the root level of my computer. Under Windows, you can install JavaHelp in C:\jh1.1; under Unix or Linux, you could install it in subdirectory jh1.1 of your home directory (or, if you have permission, in /usr/local/jh1.1). Also, take a peek ahead to Chapter 8. In Section 8.3, I discuss matching JavaHelp to a computer's Java processing environment.

When you install the JavaHelp distribution, pay close attention to any README file that Sun includes. As JavaHelp is developed further, its requirements may change. For example, the version I used for writing this book required shell commands to launch a JavaHelp system. However, when Sun released a newer version of JavaHelp, they provided a graphical user interface (GUI) tool to handle this task. The only way to know what is current is to keep up with Sun's documentation.

After you install JavaHelp, download the sample files used in this book (http://examples.oreilly.com/creatingjavahelp). There are HelpSets and small Java applications, all of which are designed to help you learn JavaHelp. Each set of sample files is compressed. To use them, decompress the files and read the enclosed

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

JavaHelp is intuitive and functions similarly to other online help systems. If you are familiar with WinHelp or HTML Help, you should have no problem navigating through a JavaHelp system. This section guides you through working with a JavaHelp system and shows you how JavaHelp's basic features work.

If you have not yet downloaded the sample files discussed earlier in this chapter, you should do so before continuing. While the screen shots in this section provide a sufficient "look" at JavaHelp, only the system itself can provide you with its actual "feel."

The way users will start the JavaHelp system depends on how you connect it to an application or applet. Usually, it is as simple as clicking a button or selecting a menu item. To run a JavaHelp system independently of an application (for example, when you are testing a HelpSet), use the hsviewer utility Sun includes with JavaHelp. Under Windows, you can launch the hsviewer utility through a shortcut created in the Start menu when you installed JavaHelp. Under Unix or Linux, you can find hsviewer in the demos/bin subdirectory in the JavaHelp installation area.

The HelpSet Viewer starts by displaying a simple file-selection dialog. Specify the HelpSet filename and the URL of the directory where it resides, as shown in Figure 1.3.

Figure 1.3: HelpSet Viewer: specifying a HelpSet

Give it a try: specify the Aviation HelpSet file and URL in the hsviewer utility. The easiest way to do this is to click the Browse button and browse for the HelpSet file. Once you have specified the HelpSet name and directory URL, click the Display button to load the HelpSet into the JavaHelp system.

After you load the Aviation HelpSet, take a look at the HelpSet Viewer's structure. As discussed earlier, the standard HelpSet Viewer uses a tripane window to display its menus, toolbar, navigation controls, and help topics. As you saw in Figure 1.1, the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The way you present a HelpSet to users can be as important as the help content itself. If users have a hard time accessing the help system, they might become reluctant to use it. The main presentation options for a HelpSet are standalone help, context-sensitive help (screen-level or field-level), and embedded help.

A standalone HelpSet is one that the user views independently of an application. When the user calls for help (either while running the application or at another time), the HelpSet Viewer appears with an overview topic in the content pane. From this initial point, users must navigate through the help system to find the topics in which they are interested. Navigation controls are very important to a standalone HelpSet, because they are the only means the user has to access detailed information.

The Aviation HelpSet used in this book is an example of a standalone HelpSet. You launch it manually and then navigate through the HelpSet's topics. A straightforward alternative is to have an application launch a standalone HelpSet when the user invokes the application's help command.

Standalone HelpSets are sufficient for supporting an application, but what if you want to provide a friendlier help system to your users? You might want to provide help through context-sensitivity. Context-sensitivity simply means that the help system displays a help topic specific to the given situation at the time the user requests help. There are two types of context-sensitive help, both are available with JavaHelp. The first type is called screen-level help. With screen-level context-sensitive help, the user is working in a particular application screen that has a button to activate help. When the user clicks that button, the help system starts and displays the specific help topic for the active screen. The user can also navigate through the help system to view other topics.

The second type of context-sensitive help is called

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

JavaHelp itself is network-capable: the HelpSet Viewer can load a HelpSet from the computer where it is running or from a remote computer. When deciding how to install a particular HelpSet, take into account the network-capability of the application for which you're providing help. The following sections present appropriate installation decisions for several kinds of applications.

A local application is one that runs on the user's computer without interaction with any other computer (via a web browser or other type of network connection). When users request help, the application launches the help system locally—that is, on the same computer. In this situation, it is best to install the application and your HelpSet together on the computer, in a single installation process. If the application doesn't rely on access to a network, neither should the help system.

In a network application, users might have a small part of the application installed on their computer (the client) and access the rest of the application on one main computer on the network (the server). Since a network is required to run the application, it makes sense to install the HelpSet on the server. When users access help on the client computer, the request goes across the network to access the necessary HelpSet files on the server, and then returns the information to display it in the HelpSet Viewer on the client.

I recommend this installation option for any network application. Since users must be connected to the server to run the application, it makes sense to take advantage of the larger disk space usually associated with network servers. What about the performance hit? In most corporate networks, the delay involved in accessing the help files across the network should be quite acceptable. Any performance issues are probably outweighed by the advantages in disk usage and administration. It would be a waste to install the HelpSet on multiple client computers when you have the option to install them once, on the server. If you need to update the HelpSet files later, you can do so in one location instead of multiple locations.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

A HelpSet consists of multiple files—one for each help topic, one for each graphic, and several JavaHelp-specific files (HelpSet file, map file, etc.). In designing your installation strategy, consider whether you want to encapsulate all these files into a single Java archive (JAR) file. To minimize storage requirements, the utility that creates a JAR file compresses the data automatically.

Even if you have never heard of JAR files before, you might be more familiar with them than you think. JAR files are very similar to the popular ZIP files. In fact, if you have a ZIP utility, you can decompress and examine the contents of JAR files.

JavaHelp works the same way, whether or not you install the HelpSet as a JAR file. The only difference is that the HelpSet Viewer must extract individual HelpSet files from the JAR file, which involves a minor performance hit. In Chapter 8, I discuss JAR compression in greater detail and provide tips for when and when not to use JAR files.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

When you have completed this book (or better yet, while you are reading it) you can obtain the latest JavaHelp information from Sun Microsystems' web site, which contains the following sources of JavaHelp-related information:

The official JavaHelp site, located at http://www.java.sun.com/products/javahelp. The JavaHelp site offers current news such as upcoming JavaHelp releases, JavaHelp events, and involvement with third-party vendors. You can also join the JavaHelp mailing list from this site.
The Java Developer Connection (JDC), which is free to join and is located at http://developer.java.sun.com/developer. The JDC offers access to technical information such as the JavaHelp specification.
The JavaHelp discussion group, which is part of the JDC. To access this discussion group, click the Toolbar option at the JDC site to launch the JDC Applet Toolbar. From this toolbar you can run the Java GroupReader applet, which displays a list of discussion groups, including the JavaHelp discussion group. For information on using the GroupReader applet, connect to the Group-Reader applet site at http://java.sun.com/products/javahelp.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Now that you have a basic understanding of how JavaHelp works, it's time to build a small HelpSet. The purpose of this chapter is to give you some practical experience with JavaHelp before you study it in more detail. This chapter is "hands on": it walks you through the development process without lengthy explanations of the concepts behind it. The rest of this book then expands on the procedures you learn here, providing the detailed information you need to thoroughly understand JavaHelp development.

The HelpSet you'll build in this chapter—we'll call it MyJavaHelp—is even simpler than the Aviation sample introduced in Chapter 1. But the procedures for building it are nearly the same as those for building a more complex HelpSet.

To best understand the structure of HelpSet data and navigation files, you should create them on your own. However, since the topic files are in basic HTML format, you might want to simply download the file set from this book's web page instead of creating them all from scratch: use the examples at http://examples.oreilly.com/creatingjavahelp.

At the end of this chapter, you will have a functioning JavaHelp system. To get you there, this chapter provides procedures to guide you through the following JavaHelp development processes:

Creating the HelpSet's directory structure
Creating HelpSet data and navigation files
Creating help topic files
Checking your work
Testing the finished HelpSet

To access HelpSet files, JavaHelp depends on proper file and directory structure. Referring to a file by the wrong name or placing a file in a wrong directory, causes JavaHelp to fail when it tries to access the file. To ensure accurate file retrieval, start your project by setting up the HelpSet's entire directory structure. Figure 2.1 shows the directory and file structure you'll create for MyJavaHelp.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

To access HelpSet files, JavaHelp depends on proper file and directory structure. Referring to a file by the wrong name or placing a file in a wrong directory, causes JavaHelp to fail when it tries to access the file. To ensure accurate file retrieval, start your project by setting up the HelpSet's entire directory structure. Figure 2.1 shows the directory and file structure you'll create for MyJavaHelp.

Figure 2.1: Structure of the MyJavaHelp HelpSet

In general, you can use whatever directory and filenames you like. However, keep in mind the following:

It's best to use the filename extensions shown in Figure 2.1.
If you rename any data or navigation files (i.e., Map.jhm, TOC.xml, Index.xml), you must edit the HelpSet file, HelpSet.hs, which contains references to these files.

Figure 2.1 shows a directory, Topics, which contains three subdirectories (FavoriteMovies, FavoriteMusic, and Interests). In general, you can use any number of directories and subdirectories, nested to any depth. Chapter 3, provides strategies for planning the organization of your file directories and options for arranging your files. In this chapter, you'll use a very simple structure.

Start the project by creating the directory structure shown in Figure 2.1. First, create MyJavaHelp, the master directory that will hold all the data for the HelpSet. Within the MyJavaHelp directory, create the following subdirectories:

Images (to hold image files)
Topics (to hold help topic files)

Place the toplevel.gif image inside the Images directory by copying it from the JavaHelp installation area (filename

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

A HelpSet contains a set of topic files, along with a number of data and navigation files. The topic files are in HTML format; the data and navigation files are in XML (Extensible Markup Language) format. XML looks similar to HTML, but has application-specific tags, such as <mapID> and <tocitem>, instead of HTML's standardized document-formatting tags, such as <head> and <p>.

Each data and navigation file contains XML elements, most of which take the following form:

<element-name  attr-name="attr-value"  attr-name="attr-value"/>

Here, "attr" means "attribute." Each element can have any number of attributes, including none at all. The value of each attribute must be enclosed in single or double quotes. XML elements are like HTML tags (at least as far as JavaHelp is concerned).

Using your text editor, create the file HelpSet.hs in the MyJavaHelp directory, with the following contents. Be sure the capitalization is correct: XML is case-sensitive!

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE helpset
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
         "http://java.sun.com/products/javahelp/helpset_1_0.dtd">

<helpset version="1.0">
  <title>My JavaHelp System</title>
  <maps>
    <mapref location="Map.jhm"/>
    <homeID>overview</homeID>
  </maps>
  <view>
    <name>TOC</name>
    <label>TOC</label>
    <type>javax.help.TOCView</type>
    <data>TOC.xml</data>
  </view>
  <view>
    <name>Index</name>
    <label>Index</label>
    <type>javax.help.IndexView</type>
    <data>Index.xml</data>
  </view>
</helpset>

This file specifies the names of the other data and navigation files for the MyJavaHelp HelpSet: Map.jhm, TOC.xml, and Index.xml. You'll create these files in the sections that follow.

In this file, as in all XML-format configuration files, it doesn't matter whether you indent elements with spaces or tabs. But doing so

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

In JavaHelp, the contents of each help topic is defined by a file in HTML format. In this sense, JavaHelp's HelpSet Viewer is very much like a web browser.

In this section, you'll create the individual help topic files. As I mentioned before, if you want to save yourself the time and effort of typing a lot of HTML-format text, simply use the HTML topic files available at http://examples.oreilly.com/creatingjavahelp.

You've already declared, in the map file, both the names and the directory locations of the following MyJavaHelp topic files:

File Overview.htm in the Topics directory (see Example 2.1)
File Fitness.htm in the Interests subdirectory of the Topics directory (see Example 2.2)
File Computers.htm in the Interests subdirectory of the Topics directory (see Example 2.3)
File Movies.htm in the FavoriteMovies subdirectory of the Topics directory (see Example 2.4)
File Music.htm in the FavoriteMovies subdirectory of the Topics directory (see Example 2.5)

Example 2.1. Overview.htm

<html>
<head>
<title>Overview</title>
</head>
<body>
<h1>Overview</h1>
<p>Welcome to my JavaHelp system. In this help system I discuss
my interests in the following topics:
<ul>
  <li>Fitness</li>
  <li>Computers</li>
  <li>Movies</li>
  <li>Music</li>
</ul>
</body>
</html>

Example 2.2. Fitness.htm

<html>
<head>
<title>Fitness</title>
</head>
<body>
<h1>Fitness</h1>
<p>I enjoy the following fitness activities:
<ul>
  <li>Running</li>
  <li>Biking</li>
  <li>Hiking</li>
  <li>Swimming</li>
</ul>
</body>
</html>

Example 2.3. Computers.htm

<html>
<head>
<title>Computers</title>
</head>
<body>
<h1>Computers</h1>
<p>I use computers every day for both work and pleasure.</p>
</body>
</html>

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

That's all there is to creating the MyJavaHelp HelpSet. Because the directory and file structure is crucial for successfully running the help system, you should double-check your HelpSet's structure. Make sure it matches the structure shown in Figure 2.1.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

You can view your HelpSet the same way you viewed the Aviation HelpSet in the preceding chapter. Start the hsviewer utility that comes with JavaHelp and specify HelpSet.hs in the MyJavaHelp directory as the HelpSet file.

Try out the different navigation components. If the HelpSet Viewer is not already displaying the TOC, click the TOC tab to view it. Notice the top-level directory image on the first line in the TOC. This image is the toplevel.gif file you copied to your Images directory. Open a folder in the TOC, and click one of the topics to display it in the content pane.

Now click the Index tab. In the Find box, type the word interests and then press the Enter or Return key. Notice that JavaHelp highlights the entry in the index. Click any index entry to display its corresponding topic in the content pane.

Congratulations! You (and JavaHelp) have just created a functional help system.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The secret of any successful project, whether it's writing online help or building a house, is good planning. Imagine you want to drive across the country, and you decide to just jump in the car and start driving. Unless you've made the same trip several times in the recent past, you probably won't reach your destination without encountering major problems.

Developing online help is no different. Unless you have a solid plan for your project, you will likely encounter many problems. These problems can add up and negatively affect your final online help system. Project planning helps ensure that your JavaHelp project runs smoothly and that you end up with a usable online help system. It won't remove all obstacles, but good project planning will help you avoid unforeseen problems.

This chapter is about JavaHelp project planning. If you are an experienced help author, you may already have a project-planning system that works well for you. If so, you may want to skim through the chapter and look for sections that are specific to JavaHelp development. If you are new to help-authoring, you should read the entire chapter. It provides a general explanation of project planning by discussing the following topics:

General planning tasks
Planning tasks specific to JavaHelp

When planning your project, consider using a third-party help-authoring tool to make help-authoring easier. Third-party tools automate many of the tasks for JavaHelp that would otherwise be tedious and time-consuming. Chapter 9, covers JavaHelp-authoring tools and explains why you should understand how JavaHelp works even when using a help-authoring tool to create a HelpSet.

Project planning is highly subjective. If you ask several help authors how to plan a project, you'll probably get several different answers. These differences can be both good and bad. Differences in opinion and new ideas are what drive theory and technology forward. However, for a new help author trying to get some direction on how to plan a new online help project, mixed opinions could only complicate matters. In the following sections, I compare several project-planning theories. My intent is not to claim that other theories are wrong but instead to help you determine a good practice for yourself.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Project planning is highly subjective. If you ask several help authors how to plan a project, you'll probably get several different answers. These differences can be both good and bad. Differences in opinion and new ideas are what drive theory and technology forward. However, for a new help author trying to get some direction on how to plan a new online help project, mixed opinions could only complicate matters. In the following sections, I compare several project-planning theories. My intent is not to claim that other theories are wrong but instead to help you determine a good practice for yourself.

Project planning is quite involved—so involved that authors write entire books on the subject. Since this book is about developing JavaHelp projects, I discuss only project-planning topics I think will help you develop a solid JavaHelp project. If you find a need or desire to learn more about project planning, I encourage you to pick up a book on the subject. In this section, I discuss some general concepts of project planning for online help systems.

Before you can outline or write online help topics, you must know the audience of the help system. Start your project by defining your audience. Doing so will help you determine the content of your online help topics, the audience's experience level, any additional elements you should include (such as images or multimedia), the way the audience should access the help system, and any special considerations for navigation. Careful audience definition will help you accurately perform the rest of the project planning and online help development tasks.

In most cases, defining the audience of an online help system essentially means defining the users of the software for which the help is written. For this reason, I use the words audience and users interchangeably.

There are many ways to learn about your audience. The important thing is to use all possible resources to find as much information about them as possible. Depending on the resources you have available, you should consider the following options for learning about your audience:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

In addition to general project planning concepts, you must focus on tasks specific to JavaHelp development. Because of the function and features of JavaHelp, you must also consider several factors when planning your JavaHelp project.

The way in which a HelpSet is presented to users—as standalone, context-sensitive, or embedded help—dictates how much extra time you need for development. During most of the development cycle, you'll access the HelpSet in a standalone manner. If your goal is to have a standalone HelpSet, you need only a mechanism for launching the JavaHelp system. In many situations, however, you have to improve usability by presenting the HelpSet as context-sensitive or embedded help.

For context-sensitive help, you must account for the time involved in assigning map IDs (from the map file) to the appropriate controls in the application. The amount of time to budget depends on how you connect the context-sensitive help. If you only connect context-sensitivity for the application's windows, it shouldn't take too much time to assign map IDs. However, if you are providing field-level help and must assign map IDs for every object and every window, you should study the application's interface to estimate the number of objects assigned map IDs.

If you are a technical writer, implementing embedded help requires close coordination with the application developer because embedded help is part of the application's interface. Discuss embedded help early during project planning, so the developer can plan for it.

When you plan your JavaHelp project, you must consider how the HelpSet will be installed at the user's site. In Chapter 1, I discussed different JavaHelp installation methods. It's important to decide on a method early enough to plan for it. You should also consider how your decision might affect the use of enhancements in your HelpSet. Earlier in this chapter, I discussed considerations for enhancing your HelpSet with images or multimedia. You must be careful with such enhancements because you don't want to frustrate your audience by making them wait for file downloads. In general, use the following guidelines for incorporating images and multimedia:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

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

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

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

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

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

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."

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

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:

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.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

It is quite possible that you may start a JavaHelp project with all of your HTML topic files already created. For example, you may be converting a preexisting HTML-based help system to JavaHelp, or may simply have created all your HTML topic files before beginning your JavaHelp-level work.

If you are using preexisting HTML files, rest assured that your workload for creating the HelpSet will be nearly the same as if you created the HTML files specifically for your HelpSet. Remember, JavaHelp uses HTML for its topic files. All you have to do is point to the HTML files in your map file. You should, however, perform a quick check to make sure the HTML files meet the standards I discussed in this chapter. For example, you should check that your HTML files don't contain markup tags or script that the HelpSet Viewer can't interpret. You should also check that each file has a title specified with <title> tags, for use by JavaHelp's word-search index.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

HelpSet data and navigation files connect the HTML-format help topic files of your HelpSet. To show you how to create HelpSet data and navigation files, this chapter discusses the following topics:

Understanding XML
Creating the HelpSet file
Assigning map IDs to help topics
Specifying the navigation components

The JavaHelp map, TOC, index, and HelpSet files are all written in the Extensible Markup Language (XML). Like HTML, XML is a web standard, but it's more flexible. You can use XML to format any kind of textual data, not just web pages. In addition, you can use XML to describe the structure of textual data, which is how XML is used in HelpSet data and navigation files.

The map, TOC, index, and HelpSet files for the Aviation sample project contain markup tags you don't find in HTML files. For example, look at the following line from the TOC file:

<tocitem target="intro" text="Introduction to Aviation">

The <tocitem> tag is not a standard HTML tag. A standard web browser simply skips over this tag, but JavaHelp's HelpSet Viewer does know how to interpret it.

Each XML file contains a tree-structured hierarchy of elements. That is, an element can contain other elements. In particular, the root element of the tree contains all the other elements in the file. Elements that contain other elements have this form:

<tag  name1="value1"  name2="value2">
    text and other elements go here
</tag>

This kind of element has a start-tag (for example, <tocitem ...>), and a corresponding end-tag (for example, </tocitem>).

Some elements, the leaves of the tree structure, contain no other elements. Such elements use this single-tag form:

<tag  name1="value1"  name2="value2"/>

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

The JavaHelp map, TOC, index, and HelpSet files are all written in the Extensible Markup Language (XML). Like HTML, XML is a web standard, but it's more flexible. You can use XML to format any kind of textual data, not just web pages. In addition, you can use XML to describe the structure of textual data, which is how XML is used in HelpSet data and navigation files.

The map, TOC, index, and HelpSet files for the Aviation sample project contain markup tags you don't find in HTML files. For example, look at the following line from the TOC file:

<tocitem target="intro" text="Introduction to Aviation">

The <tocitem> tag is not a standard HTML tag. A standard web browser simply skips over this tag, but JavaHelp's HelpSet Viewer does know how to interpret it.

Each XML file contains a tree-structured hierarchy of elements. That is, an element can contain other elements. In particular, the root element of the tree contains all the other elements in the file. Elements that contain other elements have this form:

<tag  name1="value1"  name2="value2">
    text and other elements go here
</tag>

This kind of element has a start-tag (for example, <tocitem ...>), and a corresponding end-tag (for example, </tocitem>).

Some elements, the leaves of the tree structure, contain no other elements. Such elements use this single-tag form:

<tag  name1="value1"  name2="value2"/>

Alternatively, you can also use the separate start-tag/end-tag for such elements:

<tag  name1="value1"  name2="value2"></tag>

An element can have any number of " name=value" pairs, which are called attributes. JavaHelp makes heavy use of attributes. The value of an attribute must be enclosed in quotes. In general, you can use either single quotes or double quotes; this book uses double quotes only.

The following excerpt from the Aviation TOC file contains both kinds of elements:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy reprint rights for this chapter

Take a look at the HelpSet file for the Aviation JavaHelp sample. I like to keep filenames simple, so I named it HelpSet.hs. Another good name would be Aviation.hs. Regardless of what you name the HelpSet file, you must use the .hs filename extension; the HelpSet Viewer won't open it otherwise.

Using a text editor, open the file HelpSet.hs. It contains the following code:

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE helpset
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
         "http://java.sun.com/products/javahelp/helpset_1_0.dtd">

<helpset version="1.0">
  <title>Aviation Information</title>
  <maps>
    <homeID>intro</homeID>
    <mapref location="Map.jhm"/>
  </maps>
  <view>
    <name>TOC</name>
    <label>Aviation TOC</label>
    <type>javax.help.TOCView</type>
    <data>TOC.xml</data>
  </view>
  <view>
    <name>Index</name>
    <label>Aviation Index</label>
    <type>javax.help.IndexView</type>
    <data>Index.xml</data>
  </view>
  <view>
    <name>Search</name>
    <label>Aviation Word Search</label>
    <type>javax.help.SearchView</type>
  <data engine="com.sun.java.help.search.DefaultSearchEngine">
      JavaHelpSearch
    </data>
  </view>
</helpset>

This code demonstrates both HelpSet data tags and navigation component tags. I explain how to use tags to merge HelpSets in Chapter 6.

The HelpSet file begins with two optional declarations. The XML declaration (<?xml ...) and the document type definition, or DTD (<!DOCTYPE ...), identify this file as an XML document with a particular structure. This can be useful if an XML-aware program other than the HelpSet Viewer needs to access the data in this file.

The HelpSet file must contain an element hierarchy whose root element is named "helpset." Accordingly, there is a <helpset> start-tag at the top of the file and a </helpset> end-tag at the bottom. You can include an optional version

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview

Table of Contents