creating.effective.javahelp


Brought to you by ownSky! Table of Contents Creating Effective JavaHelp By Kevin Lewis Publisher : O'Reilly Pub Date : June 2000 ISBN : 1-56592-719-2 Pages : 184 JavaHelp is an online help system developed in the Java? programming language. Creating Effective JavaHelp covers the main features and options of JavaHelp and shows how to create a basic JavaHelp system, prepare help topics, and deploy the help system in an application. Written for all levels of Java developers and technical writers, the book takes a chapter-by-chapter approach to building concepts, to impart a complete understanding of how to create usable JavaHelp systems and integrate them into Java applications and applets. ii Table of Content Table of Content......................................................................................................ii Preface......................................................................................................................v Audience...............................................................................................................v About This Book..................................................................................................v Assumptions This Book Makes........................................................................vi Conventions Used in This Book.......................................................................vi Comments and Questions ...............................................................................vii Acknowledgments.............................................................................................vii Chapter 1. Understanding JavaHelp....................................................................1 1.1 What Is JavaHelp? .......................................................................................1 1.2 Using JavaHelp for Online Documentation ..............................................3 1.3 Understanding the Files in a HelpSet........................................................4 1.4 Following the JavaHelp Process................................................................5 1.5 Installing JavaHelp on Your Computer .....................................................6 1.6 Seeing JavaHelp in Action ..........................................................................6 1.7 Deciding How to Present a HelpSet........................................................11 1.8 Deciding How to Install a HelpSet ...........................................................12 1.9 Encapsulating HelpSet Files.....................................................................13 1.10 Finding More Information on JavaHelp.................................................13 Chapter 2. Creating Your First HelpSet.............................................................14 2.1 Creating the HelpSet's Directory Structure ............................................14 2.2 Creating HelpSet Data and Navigation Files .........................................16 2.3 Creating Help Topic Files..........................................................................19 2.4 Checking Your Work ..................................................................................21 2.5 Testing the Finished HelpSet ...................................................................21 Chapter 3. Planning the JavaHelp Project ........................................................22 3.1 General Planning Tasks............................................................................22 3.2 Planning Tasks Specific to JavaHelp ......................................................29 Chapter 4. Preparing Help Topics......................................................................33 4.1 Planning Your Help Topics .......................................................................33 4.2 Creating Help Topics and Applying Appropriate HTML Tags .............35 4.3 Writing Effective and Meaningful Help Topics .......................................38 4.4 Using Preexisting HTML Topic Files .......................................................41 Chapter 5. Creating HelpSet Data and Navigation Files ................................42 5.1 Understanding XML ...................................................................................42 5.2 Creating the HelpSet File ..........................................................................43 5.3 Assigning Map IDs to Help Topics...........................................................45 5.4 Specifying the Navigation Components..................................................47 Chapter 6. Enhancing the HelpSet.....................................................................56 6.1 Creating Pop-up and Secondary Windows ............................................56 6.2 Customizing the Navigation Facility.........................................................61 6.3 Merging HelpSets.......................................................................................68 Chapter 7. Using the JavaHelp API for Advanced Presentation Options ....73 7.1 The TypeFacer Application.......................................................................73 7.2 Invoking Help with a Button, Menu Item, or Key ...................................76 7.3 Using Screen-Level Context-Sensitive Help ..........................................78 iii 7.4 Using Field-Level Context-Sensitive Help ..............................................81 7.5 Embedding Help into the Application ......................................................83 Chapter 8. Deploying the Help System to Your Users....................................88 8.1 Encapsulating the HelpSet........................................................................88 8.2 Delivering All the Required Files..............................................................89 8.3 Ensuring Basic Java Support ...................................................................90 Chapter 9. Using Third-Party Help-Authoring Tools........................................91 9.1 How JavaHelp Relates to Third-Party Tools ..........................................91 9.2 How Third-Party Tools Work.....................................................................91 Appendix A. HelpSet Tags...................................................................................96 A.1 Map File.......................................................................................................96 A.2 TOC File ......................................................................................................96 A.3 Index File.....................................................................................................97 A.4 HelpSet File.................................................................................................97 Appendix B. Lightweight Component Tags.....................................................100 B.1 Pop-up and Secondary Windows ..........................................................100 Appendix C. The JavaHelp API ........................................................................104 C.1 Classes in Package javax.help..............................................................104 C.2 Classes in Package javax.help.event...................................................119 Appendix D. TypeFacer.java Source Listing...................................................121 Glossary................................................................................................................128 Colophon ..............................................................................................................131 4 Copyright © 2000 O'Reilly & Associates, Inc. All rights reserved. Printed in the United States of America. Published by O'Reilly & Associates, Inc., 101 Morris Street, Sebastopol, CA 95472. Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademarks, and The Java™ Series is a trademark of O'Reilly & Associates, Inc. The association of the image of a flashlight with the topic of JavaHelp™ is a trademark of O'Reilly & Associates, Inc. Java™ and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries. O'Reilly & Associates, Inc. is independent of Sun Microsystems. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O'Reilly & Associates, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. While every precaution has been taken in the preparation of this book, the publisher assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. v Preface This book is about JavaHelp™ from Sun Microsystems. JavaHelp is an online help system developed for 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. JavaHelp can be used for many online documentation purposes, but its primary function is to provide an online help system to support Java applications. Of course, as with any new online help system, people have many questions they need answered and demands they need addressed. This book attempts to address those questions and demands and teaches you how to develop usable online help systems with JavaHelp. To provide a comprehensive look at JavaHelp development, this book covers the main features and options of JavaHelp by presenting the following topics: • Understanding JavaHelp • Creating your first HelpSet • Planning the JavaHelp project • Preparing help topics • Creating HelpSet data and navigation files • Enhancing the HelpSet • Using the JavaHelp API for advanced presentation options • Deploying the help system to your users • Using third-party, help-authoring tools Audience While it would probably suffice to say that this book is for any person interested in learning JavaHelp and developing usable JavaHelp systems, I can think of two specific groups of people who will likely get the most out of this book: Java developers and technical writers. Many Java developers don't have technical writers to handle software documentation. If you are one of these developers, you will find this book a great supplement to your other O'Reilly Java books. You might not have the need or desire to read the book cover to cover(although I recommend you do), but you will find that specific sections give you the information you need. You will want to read at least this Preface and Chapter 1, to learn how to create a basic JavaHelp system. You should also scan the book for tips on making your help system usable. The book is also designed for technical writers, who are faced with the challenge of learning many types of documentation systems. As more applications are developed in the Java programming language, you will find a strong need to learn the JavaHelp system. This book will help you learn to develop JavaHelp systems quickly and easily. If you need to master online help systems, you will probably want to read the book cover to cover. However, if you are experienced with online help design and authoring, I have clearly identified sections so that you will know when you can skip over material. About This Book vi This book covers the main features and options of JavaHelp. It presents concepts, chapter by chapter, until you have a complete understanding of how to create usable JavaHelp systems and how to integrate them into applications and Java applets. The key phrase here is create usable JavaHelp systems. I emphasize this phrase because this book not only teaches you how to create JavaHelp systems but also provides tips for making those systems usable. If you are an experienced help author, you may not need this extra information. But if you are creating a help system for the first time, you may find that the help-authoring tips are quite helpful. Use them and your application users will be thankful. Now that you know what this book is about, I should explain what this book is not about. This book is not a manual that focuses on the technical aspects of the JavaHelp application programming interface(API). In fact, you won't find a lot of low-level technical information about JavaHelp in this book. I do cover enough technical information to help you understand how JavaHelp works, and I provide code samples to help you understand how to deploy JavaHelp with your applications. However, the book's focus is primarily on how to work with JavaHelp and how to design and create usable JavaHelp online help systems. If you are interested in learning more about lower-level technical specifications of JavaHelp, you can access technical documents through Sun Microsystems' Java Technology web site at http://www.javasoft.com. One technical document in particular you might want to review is the JavaHelp specification. Assumptions This Book Makes As you will learn in this book, you must write JavaHelp topics(the actual help topics that make up the JavaHelp system) in HTML. Since this book is about JavaHelp and not HTML, it assumes you have a basic understanding of HTML. I'm not saying you have to be a webmaster or an HTML programmer, but you must have a basic understanding of HTML tags and how to use them. I provide ideas on how to format your topics, but I don't stop to explain what the HTML behind them means. If you have no experience with HTML, have no fear. All you will need is a good HTML editor to create your help topics. You may also want to refer to HTML: The Definitive Guide, by Chuck Musciano and Bill Kennedy(O'Reilly & Associates), as an HTML reference. I refer to this book many times when creating HTML topic files. Conventions Used in This Book The following font conventions are used in this book: Italic is used for: • Unix pathnames, filenames, and program names • Internet addresses, such as domain names and URLs • New terms where they are defined Boldface is used for: • Names of GUI items: window names, buttons, menu choices, etc. Constant width is used for: • Command lines and options that should be typed verbatim vii • Names and keywords in Java programs, including method names, variable names, and class names • XML element tags Comments and Questions The information in this book has been tested and verified, but you may find that features have changed(or you may even find mistakes!). You can send any errors you find, as well as suggestions for future editions, to: O'Reilly & Associates, Inc. 101 Morris Street Sebastopol, CA 95472 (800) 998-9938(in the United States or Canada) (707) 829-0515(international/local) (707) 829-0104(fax) You can also send messages electronically. To be put on the mailing list or request a catalog, send email to: info@oreilly.com To ask technical questions or comment on the book, send email to: bookquestions@oreilly.com There is a web site for the book, where examples, errata, and any plans for future editions are listed. The site also includes a link to a forum where you can discuss the book with the author and other readers. You can access this site at: http://www.oreilly.com/catalog/creatingjavahelp For more information about this book and others, see the O'Reilly web site: http://www.oreilly.com Acknowledgments One of the most important chapters in this book, Chapter 7, would not have been possible without Marc Loy. The chapter is technical and required the touch of a talented Java developer. Marc wrote most of the first draft for me to make sure the chapter included the appropriate level of information for Java developers. As part of his work on the chapter, Marc also developed the small sample application that demonstrates the Java code for implementing JavaHelp. Finally, Marc also put together Appendix C. Thank you, Marc, for being so generous with your time and Java programming talents. This book would not be complete if it weren't for your help. I am also indebted to Alicia Norton, a colleague and extremely talented technical writer, for reviewing, editing, and testing every chapter of this book while I was writing it. Her efforts helped viii me turn in cleaner chapters during the writing process. Thank you, Alicia, for your feedback. And thank you for your encouragement throughout the entire book-writing process. Thanks to O'Reilly—especially Mike Loukides—for your help and for the opportunity to write this book. Thanks to John Posner for all of your editing efforts when I finished the book. Also, thanks to Robert Romano for your help with the illustrations. Sun Microsystems should be proud of their JavaHelp development team—particularly Larry Hoffman and Roger Brinkley—who answered my many, many emails, often within hours(and sometimes within minutes). I must express gratitude to Dr. Kristin Woolever, my first technical writing teacher and mentor, for teaching me most of what I know about technical writing. Without you as a role model, Kristin, I would never have learned about computer writing and could never have written this book. Finally, for all of my friends who had no idea what I've been writing about: read this book, and you'll finally understand what JavaHelp is. 1 Chapter 1. Understanding JavaHelp 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 1.1 What Is 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 . 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 2 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: Application-level help The user enters at a top level, such as an introductory topic or a table of contents. Screen-level help The user clicks a button to launch the help system with a specific help topic that describes the application's current screen. Field-level help The user selects a specific application control(such as a text box or button) on which to obtain help. Embedded help The help system is built directly into the application's interface. If you are familiar with other help systems, you might be thinking, "So what's new?" JavaHelp's unique feature is that it is developed in the Java programming language. Therefore, Java programming can enhance the HelpSet Viewer to match your project's custom needs. Also, JavaHelp integrates seamlessly with Java applications. Since JavaHelp runs with the Java platform, it runs in the same process as the Java application for which it is created. 3 1.2 Using JavaHelp for Online Documentation 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. 1.2.1 Why Use JavaHelp for Online Help? 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. 1.2.2 Comparing JavaHelp with Other Help Systems 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. I've already explained why JavaHelp is the perfect solution for Java applications. Actually, JavaHelp will probably solve the majority of your online documentation needs whether you're working with Java applications or not. For example, as you will read in the next section, you can use JavaHelp for online books, such as reference manuals or user's guides. The only situation where I would not recommend using JavaHelp is when you want to incorporate an online help system into a non-Java application. Because of the different environments, other online help systems are better for different platforms. For example, an application developed with Visual Basic would not be well suited for JavaHelp. You could certainly use JavaHelp, but using the Java runtime environment only for the online help system would not be worth the required resources. Instead, a more compatible online help system such as WinHelp or HTML Help would work better with the application and integrate more smoothly with the development environment. 1.2.3 Using JavaHelp for General Online Documentation 4 JavaHelp is not only a solution for providing online help with Java applications. Since JavaHelp is platform-independent, it offers a solution for general online documentation. Online books and reference material can be distributed through JavaHelp, since users of all platforms can access it. For example, the Aviation document illustrated in Figure 1.1 could be an online reference document independent of any software application. You could create something similar for reference manuals, user's guides, product specifications, and just about any other type of document you can imagine. When you compare other options for online books, JavaHelp emerges as a viable solution. For example, you could use ASCII text files to distribute cross-platform documentation; however, you would not be able to use user-friendly navigation controls or add images and text formatting as with JavaHelp. If you want to use a more sophisticated documentation tool(such as Microsoft Word) to add navigation, images, and text formatting to your documentation, you have to deal with more complex issues with regards to portability and user software requirements. 1.3 Understanding the Files in a HelpSet 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. 5 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 you provide to implement a particular online help project. The word-search index is a bit more complex; it refers to a folder that contains several files. You create these files using an indexing utility Sun provides with JavaHelp. The indexing utility builds a full-text search database for the HelpSet. The database is then searched when users type in a specific word under the word-search tab in the navigation pane. The actual topic files for a HelpSet are HTML files. You can have only one topic per HTML file because the map file assigns one map ID to one HTML file. The topic files can include images and links just as with ordinary HTML pages. Additionally, you can use controls for pop-up windows, secondary windows, and multimedia clips. 1.4 Following the JavaHelp Process 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. 6 1.5 Installing JavaHelp on Your Computer 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. What About JavaHelp 1.0? JavaHelp 1.0 is no longer available on Sun's JavaHelp web page. Since any work done in JavaHelp 1.0 is completely compatible with JavaHelp 1.1, I highly recommend switching to JavaHelp 1.1 regardless of which Java development environment you use. 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 ReadMe.txt file for more information. To help you learn JavaHelp concepts, some chapters instruct you to change the original code in certain sample files. Before making any changes, you should back up the entire folder containing the original files. This backup prevents you from permanently losing the files' original information after you modify them. Each exercise assumes you are starting with the original files downloaded from this book's web site. 1.6 Seeing JavaHelp in Action 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. 7 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." 1.6.1 Starting the JavaHelp System 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. 1.6.2 Working with the JavaHelp Interface 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 toolbar pane contains the menu and toolbar, which offer menus and controls to assist you in viewing the current HelpSet. The navigation pane contains a TOC, index, or word-search index. The content pane displays the current help topic. You can not only read the topic's content in this pane but can also access pop- up and secondary windows for expanded information, launch multimedia clips(if you have a multimedia component), and follow hyperlinks to other topics or web pages. Hyperlinks can lead not only to HTML pages in the current HelpSet, but also to web sites on the Internet, as shown with the avbook.com link in the Aviation introductory topic.(The HelpSet Viewer cannot display all HTML-format files. See Chapter 4, for more information.) 1.6.3 Using Toolbar Controls and Menus The JavaHelp toolbar contains previous and next buttons, similar to those found in web browsers. The previous and next buttons enable you to browse back and forth through topics you have previously viewed. They do not advance you back and forth in order of the help topics as they exist in the TOC. Like a web browser, these buttons are not enabled until you begin navigating through the help system and have viewed topics to which you can move back and forth. 8 The toolbar also contains print buttons next to the previous and next buttons. You use the print buttons to set up the page's print options and to print the help topic that is displayed in the HelpSet Viewer. As you read a help topic, you might find that you would rather display the topic in the entire viewer instead of taking up space for the navigation pane. You can easily show and hide the navigation pane using buttons, as shown in Figure 1.4. Figure 1.4. HelpSet Viewer: showing and hiding the navigation pane There are also menus at the top of the HelpSet Viewer. These menus offer basic functions such as opening a web page, selecting a new HelpSet, or setting font preferences. If you click Open page from the File menu, the HelpSet Viewer displays the window shown in Figure 1.5. Figure 1.5. HelpSet Viewer: opening a help topic or web page You can use this window to access not only topics from the current HelpSet but also HTML pages from any web site. If you are connected to the Internet, try typing http://www.oreilly.com in the URL box and then click the OK button. As you probably guessed, the HelpSet Viewer displays the O'Reilly web site. If you select Set HelpSet from the File menu, the viewer displays the same window shown in Figure 1.3 for selecting a new HelpSet. You can also change the fonts in the navigation pane by clicking Set Font from the Options menu. When the Set Font window appears, simply select a font and size. 1.6.4 Navigating Through the JavaHelp System Below the toolbar controls and menus is the navigation pane. The navigation controls are very important in any online documentation system. Online documentation is useless if users cannot find the information they need. As shown earlier in Figure 1.1, the navigation pane in the JavaHelp system provides three types of navigation controls(or navigators): 9 • TOC • Index • Word-search index(known as the Find feature in other online help systems) You access each navigation control by clicking its associated tab, as shown in Figure 1.6. Figure 1.6. JavaHelp navigation controls The TOC provides navigation information similar to the TOC of a book. Individual topics are grouped into categories(like sections of a book are grouped into chapters). Each category(represented in Figure 1.6 by a folder icon) can contain both subcategories and individual topics. You can open and close a category by double-clicking the category name or by single- clicking the level icon to its left. You view a help topic by clicking its title. Give it a try using the following steps with the Aviation HelpSet: 1. Double-click the Airplane Structure category in the TOC. An overview topic that is associated with the category appears in the content pane, and a list of help topics expands below the Airplane Structure folder in the TOC. 2. Click a help topic within the Airplane Structure category. As you would expect, the associated topic appears in the content pane. 3. Now is a good time to use the previous and next buttons in the toolbar to see how they integrate with the TOC. Click the previous button. The content pane "jumps"(backward or forward) to the previously displayed topic. Notice that the highlighted category or topic in the TOC stays synchronized with the topic displayed in the content pane. The index provides navigation information similar to the index of a book, with one distinct difference: in the JavaHelp index, you can type a word, or any character string, directly to find it in the index. Under the index tab(the middle tab), in the Find box, type the word landing(the index is case-sensitive, so be sure to use all lowercase letters as shown) and press Enter. The system highlights the first index item that matches the search string, and the index item's associated topic displays in the content pane. 10 With landing still typed in the Find box, press Enter again. As you keep pressing Enter, subsequent index items are highlighted in the index and their associated topics display in the content pane. You can also scroll through the index to select items from it. JavaHelp also offers a word-search index facility through which users can type a word or phrase and have the system display a choice of topics that contain that word or phrase. The search is case- insensitive. The helpfulness of this feature depends on the search term the user types. With a specific term, such as "metadata file," the word-search facility will probably find just the desired topics. With a general term, such as "file," the word-search facility will probably find too many topics. Give this feature a try with the Aviation HelpSet. Under the word-search index tab(the tab on the right), in the Find box, type retractable landing gear and then press Enter. The result of the word search is a list of topics. Each topic is annotated with the number of hits—the number of occurrences of the search term, exactly or approximately, within the topic. The HelpSet Viewer automatically displays the first help topic in the list of hits, with the occurrences of the search term highlighted. In the navigation pane, each hit is annotated with a number and an icon. The number indicates how often the search term appears in the help topic; the icon represents the ranking of that topic's matches, i.e., how close the text in the topic is to the specified search term. There are five possible rankings, from a full circle(highest ranking) to an empty circle(lowest ranking). For example, when you enter the phrase retractable landing gear, the viewer generates several topic titles. The title "Landing Gear" has a full circle because all of the words in the search phrase("retractable," "landing," and "gear") appear in the topic together. The title "Drag" has a half-filled circle because only two of the words("landing" and "gear") appear in the topic. The title "Airports" has an almost empty circle because only one word("landing") appears in the topic. 1.6.5 Viewing Help Topics When you access help topics using navigation controls, you can work with them as if they were in a standard web browser. You can scroll through and read topics the same way you do with a web browser. Also, hyperlinks work the same way as in a browser. When you see blue underlined text in a topic, click it to go to the topic associated with that link. You can access pop-up windows, secondary windows, and multimedia clips through help topics. To see how these features work, go through the following steps with the Aviation HelpSet: 1. If it is not already selected, click Introduction to Aviation. 2. When the help topic opens, click the JavaHelp Note button. A pop-up window appears, providing a note. You are not limited to buttons for providing pop-up windows; you can also use an image or a regular text link. 3. Click anywhere in the HelpSet Viewer(but not in the pop-up window) to close the pop-up window. 4. Click the TOC folder titled Airplane Structure. 5. When the help topic opens, click the picture of the airplane. A similar pop-up window appears. 6. Click anywhere in the HelpSet Viewer to close the pop-up window. 7. In the TOC, open the folders Flight Environment, Airports, and then Runways and Taxiways, and then click the TOC help topic titled Markings. 8. When the help topic opens, click the bulleted blue text "Runway markings." 11 This time a secondary window appears. Notice that this window looks more like a standard window than did the pop-up window. You can move, resize, and close the secondary window like a standard window. 9. Close the secondary window by clicking its close button. I discuss pop-up windows and secondary windows in more detail in Chapter 6. 1.7 Deciding How to Present a HelpSet 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. 1.7.1 Using Standalone 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. 1.7.2 Using Context-Sensitive Help 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 field-level help(also known as What's This help). This type of help is integrated with the application's interface. Users typically activate a mechanism(for example, clicking a button with a question mark) and then point to or click a control in the active window. The help system then displays a help topic that describes the selected control. Some help systems use a simple pop-up window for field-level help to save screen space. With JavaHelp, invoking field-level help launches the full HelpSet Viewer and displays the topic for that particular control. Although this method takes up more screen space and operating-system resources, it offers users an easy way to access related topics. 1.7.3 Using Embedded Help 12 Another way to increase user-friendliness is with embedded help. Embedded help is similar to context-sensitive help in that it displays the help topic associated with the current condition of the application. The difference is that embedded help is built into the interface so that the user sees it all the time. As the user switches to different windows or controls, the help remains visible, but the active topic changes to reflect the changes in the application's condition. In general, embedded help does not necessarily look like a traditional help system. Help can come in the form of icons, tips, numbered arrows, or any visual device built into the application's interface. With JavaHelp, however, embedded help is more limited: it is visual JavaHelp components(content pane, navigation pane) built directly into a Java application's user interface. 1.8 Deciding How to Install a HelpSet 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. 1.8.1 Local Application 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. 1.8.2 Network Application 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. 1.8.3 Java Applet A Java applet is an application that runs within a web browser. This probably means that the user's computer is on a corporate network(intranet) or on the Internet. In this case, you should install the HelpSet that documents the applet on the server, as described in Section 1.8.2, and have the applet access the HelpSet across the network. In the less typical case where the applet is located on the local computer, you should install the applet's HelpSet locally, as described in Section 1.8.1. 13 1.8.4 Java Product Suite Some applications have multiple Java components, each with its own online help—for example, an office suite application. The separate components of the suite might include a word processor, a spreadsheet application, and a database application. Each component would have its own HelpSet. Since the components are part of a larger application, you might want to merge all the HelpSets together, presenting a single, integrated help system to the user. 1.9 Encapsulating HelpSet Files 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. 1.10 Finding More Information on JavaHelp 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. 14 Chapter 2. Creating Your First HelpSet 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 2.1 Creating the HelpSet's Directory Structure 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 15 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 jh1.1\Demos\hs\holidays\images\toplevel.gif). This image file is the icon that appears at the top level of the TOC in the HelpSet Viewer. In the Topics directory, create the subdirectories that will contain the actual help topic files: FavoriteMovies, FavoriteMusic, and Interests Try to be consistent in devising directory names and filenames. This will help you avoid spelling errors. The name of each subdirectory contains one or more capitalized words, with no intervening spaces. This style makes a directory name easy to read and clearly indicates the directory's contents. 16 You now have the entire directory structure required for the MyJavaHelp HelpSet. 2.2 Creating HelpSet Data and Navigation Files 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 and , instead of HTML's standardized document-formatting tags, such as and

. Each data and navigation file contains XML elements, most of which take the following form: 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). 2.2.1 Creating the HelpSet File 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! My JavaHelp System overview TOC javax.help.TOCView TOC.xml Index javax.help.IndexView Index.xml 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. 17 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 does help humans read the file, since it shows how some elements are logically contained within others. 2.2.2 Creating the Map File The map file assigns a unique keyword(called a map ID) to each topic file in the HelpSet, using mapID elements: Creating a map file can be long and tedious for a HelpSet with many topic files, but it is easy for MyJavaHelp, which is very small. For simplicity, use each topic filename(without the extension) as its map ID. Using a text editor, create the file Map.jhm in the MyJavaHelp directory, with the following contents: The URLs in this map file are relative pathnames—they are relative to the directory in which the map file resides. Thus, these URLs rely on the Topics subdirectory being in the same directory as the Map.jhm file(the MyJavaHelp directory). However, if an image or topic file were in another directory or at some other site on the Web, you would have to use an absolute path, as shown in the following example: In a map file, you must use forward slashes(/) instead of backslashes(\) in the values of url attributes. That is, you specify a URL just as you would in a web browser. Also, be aware of case-sensitivity. Windows systems are case-insensitive in reading filenames(and thus, URLs); Unix systems, however, are case-sensitive. It's best to be conservative: always specify file and directory names paying close attention to case. 2.2.3 Creating the Navigation Files Navigation is an important part of any online help system. The MyJavaHelp HelpSet you are creating in this chapter is quite small, so users could easily find each topic even if you provided only a table of contents(TOC). But imagine trying to find a topic in a HelpSet that contains 200, 18 500, or more topics. With larger HelpSets, the user is dependent on a complete and usable navigation system. Even though your HelpSet is small, you should still create a complete navigation facility, including at least a TOC and index. You could also create a word-search index, but I'll defer that discussion until Chapter 5. 2.2.3.1 Creating the TOC file The TOC file uses a different set of XML elements from the map file. Using your text editor, create the file TOC.xml in the MyJavaHelp directory, with the following contents: (This is an example of a place where indentation style is critical to human readability. "When nesting gets deep, the tough reach for the Tab key.") You probably recognize the map IDs you created in the preceding section. I'll go into more detail about the TOC and other navigation files in Chapter 5. For now, note that: • The text attribute of a tocitem element specifies the title to appear in the TOC as displayed by the HelpSet Viewer. • Some tocitem elements are nested within other tocitem elements. Nesting of elements represents the hierarchy of the TOC. 2.2.4 Creating the Index File The index file resembles the TOC in structure and format. But keep in mind that JavaHelp doesn't automatically alphabetize the index items. The order of items in the index file is the order in which the items appear in the HelpSet Viewer. You'll want to allocate time(and/or help-authoring tools, as described in Chapter 9) for ensuring that the index items are in alphabetical order in the index file. Using your text editor, create the file Index.xml in the MyJavaHelp directory, with the following contents: As in the TOC file, the text attribute specifies the item to be displayed in the HelpSet Viewer. Nesting of indexitem elements defines primary and secondary index items. In this file, interests is a primary index item, and computers and fitness are secondary items. 2.3 Creating Help Topic Files 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 Overview

Overview

Welcome to my JavaHelp system. In this help system I discuss my interests in the following topics:

    20
  • Fitness
  • Computers
  • Movies
  • Music
Example 2.2. Fitness.htm Fitness

Fitness

I enjoy the following fitness activities:

  • Running
  • Biking
  • Hiking
  • Swimming
Example 2.3. Computers.htm Computers

Computers

I use computers every day for both work and pleasure.

Example 2.4. Movies.htm Favorite Movies

Favorite Movies

The following movies are some of my favorites:

  • Titanic
  • Sphere
  • Halloween
  • 48 Hours
Example 2.5. Music.htm 21 Favorite Music

Favorite Music

I enjoy the following types of music:

  • Rock and roll
  • Pop
  • Easy listening
  • Jazz

You should also see my list of favorite movies.

2.4 Checking Your Work 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. 2.5 Testing the Finished HelpSet 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. 22 Chapter 3. Planning the JavaHelp Project 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. 3.1 General Planning Tasks 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. 3.1.1 Defining the Audience 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. 23 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: Study user information based on previous releases of similar software If you are writing or updating online help for a software upgrade, use audience information from the previous release such as interviews, surveys, customer-support calls, or any other source of user feedback. If your application is new, you can look at online help from competitors' software, which may help you understand the types of users who may work with your application. Talk with customer or technical support personnel, who interact with users on a regular basis Customer or technical support personnel frequently talk with users who generally call in with problems or other feedback. Use their information and incorporate it into your online help systems. In the long run, you'll increase user satisfaction and help cut down on support calls. Talk with marketing personnel, who may have already conducted studies on their users Marketing personnel should know everything about the people buying their software. Talk with them to get information based on research they may have performed to market the product. Talk with software developers who have conducted their own user studies Software developers are in the same situation as you. They must study the potential users of their software to know how they should develop the application. Sharing information with them provides shortcuts and saves time for the entire development team. Talk with trainers who have taught classes for the users of your software Because of the nature of classroom interaction, trainers probably know the questions most frequently asked by your users. Talk with them and generate a list of frequently asked questions. Use this information when planning the topics for your HelpSet. Assess the nature of the software Look at the software itself to define the audience. For example, if the software is a sophisticated data-warehousing tool, you know your audience consists of database programmers and other technical people. On the other hand, if the software is an S.A.T. preparation course, your audience consists of high-school students who are preparing for college. The language you use for these two audience types and the experience level you assume are completely different. 3.1.2 Determining the Audience's Needs 24 Once you have determined your audience, you can define their needs. There are many aspects to consider when defining the audience's needs. You must consider every situation your users are in as they use the software and access its online help. Consider the following factors as you define your audience's needs: Input from users Some companies perform complete needs analyses by talking with potential users of their application. If you are part of such a company, you can ask those users what they need and want in an online help system. Need for context-sensitive and embedded help Depending on the users of your software, context-sensitive and embedded help can be a great service. People with little computer experience would welcome such help because it reduces their workload. With context-sensitive help, the system displays the appropriate information based on the application's current situation. Embedded help makes using online help easy since it's always displayed. Context-sensitive and embedded help are usually welcomed by novice users, who need a lot of assistance. However, expert users might become a bit annoyed with embedded help if the application is always forcing online help on them. Experience level of users I just mentioned one example of considering different users' experience levels. There are, however, many more considerations. The style you use to write every help topic depends on the experience level of your users. Experienced users are comfortable with technical terms, while novice users need concepts presented in simple terms. Be sure to gear your information toward the right user level. Always plan for the "lowest common denominator." If you have a mix of users, make sure you write for the lowest experience level and use an intuitive navigation design so that users of all experience levels can find the appropriate information. Age of users You should consider the age of your users when writing your help topics. The language and tone you use in your writing will be different for a teenager than for an elderly person. The way you come across to your audience determines the credibility you establish with them. Situation under which users work with the application The situations under which users work with your application will dictate a large amount of their needs. For example, if the application supports work performed in an office or other business setting, users are probably rushed while working with the application. If users work with the application at home, they are probably not as rushed. You could probably imagine the difference in the way you would have to deliver online help for an application that helps air traffic controllers land aircraft compared to an application that helps people plan a family vacation. Any disabilities or challenges the user may have Don't overlook the possibility of disabilities your users might have. Simple tasks, such as moving the mouse and clicking a button, can be difficult for people with certain physical disabilities. If your software is designed to assist people with physical disabilities, you 25 should consider how embedded and context-sensitive help could work with the application. Embedded and context-sensitive help can relieve the user of having to frequently access help and search for specific topics. 3.1.3 Planning Integration with Hardcopy Documentation A misconception among some help authors is that you can simply convert hardcopy documentation to electronic documentation, throw in a TOC and index, and then end up with a usable online help system. This practice does little to help your audience. The way people use online help is very different from the way they use hardcopy documentation. You therefore must consider how your online help will integrate with any hardcopy documentation included with your application. A common-sense approach is to think about how you read documentation yourself. When you first purchase software and want to read overview material to understand the basic concepts of how the application works, you probably don't want to run the online help and start reading a lengthy explanation on the screen. Instead, you probably would rather open up a book, grab a comfortable seat, and read about the basics of the application. Conversely, if you are in the middle of a procedure with the application and quickly need to refer to instructions, you don't want to interrupt your workflow to go grab a book off the shelf. Instead, you want to click a button that launches the online help and view the instructions while working with the application. When planning the content of your online help system, you should determine if certain material should be presented online or if it would be better presented in a book. In general, the following types of information work well in online help: • Short, general concepts that help users better understand the tasks they are trying to perform • Procedures for tasks • Brief reference material • Troubleshooting information for performing tasks Notice that for troubleshooting information I said for performing tasks. Troubleshooting for system problems(as opposed to task-related problems) should be placed in a hardcopy manual. If users have problems and can't run the software application, they might not be able to access the application's online help. System-related troubleshooting information does little good in a help system if users can't access it. You should also consider whether or not you will be providing context-sensitive help. There is no need to explain the application's windows and controls in hardcopy documentation if you will be doing so with field-level help. Users want to know what controls do when they are thinking of using them—not when they are trying to understand the basics of the application. One trick I use when deciding how to integrate the online help with hardcopy documentation is to picture the user reading the online help while working with the application and trying to accomplish a task. I then picture the same user reading nonreference hardcopy documents(such as a user's guide or getting-started book) away from the computer. From these models, I decide what information users need in each situation and place the information appropriately. 3.1.4 Creating an Outline Before you put your online help system together, create an outline. The outline will be the blueprint for your online help system. A good outline should include every aspect of your help system including types of help topics, content, navigational structure, images, multimedia, and other enhancements you need for your system. 26 During the project-planning stage, you probably won't know everything about the application for which you are writing help. For this reason, you can't expect your outline to include a list of every help topic in the final HelpSet. Instead, come up with general subjects from which you can develop the final help topics. You should also consider the need for images, multimedia, and other enhancements. You will need to have an idea of the quantity of these enhancements so that you can estimate their development time when you create a schedule. One important aspect to consider is how the users will access the help system. If the help system supports a web-based applet, and users will be connecting to the Web with a modem, you have to plan a system with smaller files. Using a modem, your audience won't want to wait for larger files to download. This demand requires you to minimize the use of larger files such as images and multimedia. If your users access the applet through a local network, you can afford to use larger files since there is usually little download time over local networks. Another consideration is whether the users install the application directly on their computer. In this situation, you need to consider the size of your files, not because of their download time, but because you don't want a lot of space taken up by help files. If you plan on using multimedia, consider storing the multimedia files on a CD-ROM and accessing them from the CD-ROM as needed. Of course, these scenarios reflect only a fraction of the possible needs your users may have. The bottom line is that your outline must account for the needs you determine in the early planning stages. The best way to demonstrate the outline is through an example. 3.1.4.1 Example of a general outline Suppose you want to create an outline for the online help system of a word processing application. You would first outline the types of help topics, along with their general content. You would probably decide to have field-level help for every control on every screen in the application. This type of help would contain only brief descriptions of the controls' functions. You would also want to estimate how many controls are needed for field-level help. This knowledge will help you later when you schedule your project tasks. You also should have conceptual and procedural help—the type of help users see when they click a Help button. You would probably decide that you want conceptual and procedural help for topics such as creating new documents, formatting text, using editing tools, incorporating images, as well as other topics related to the word-processing application. Again, you should try to estimate the number of help topics you will need to schedule the project tasks. The application will run directly on the user's computer, so you don't have to worry about download time for images. You might decide to use multimedia clips since you found that many novice users new to word processing will be using the application. To provide multimedia, you will want to plan on incorporating the clips on a CD-ROM. You will probably end up with an outline similar to the one shown in Figure 3.1. In reality, of course, your outline would be much longer since you would have more topics and longer descriptions. Figure 3.1. A help project outline 27 3.1.5 Testing Your Outline Once you have an outline, you should test it. There are many ways to test your outline depending on available time and resources. If you have minimal time and resources, a test can be as simple as giving the outline to potential users to see if the proposed system answers their questions. If you have ample time and resources, the test could mean setting up a role-playing environment where users simulate working with the application while you simulate providing online help based on the topics in your outline. Whatever means you use to test the outline, your goal is the same. By testing your outline, you are making sure it covers the information needed by your audience. If you find there are holes in your outline, you can go back and fix the outline before you use it to schedule tasks. 3.1.6 Scheduling Project Tasks As with project planning in general, different help authors have different opinions on how to schedule tasks. Some help authors prefer to schedule the entire project at the beginning of project planning. Their theory is that, by scheduling at the beginning of project planning, you can add in the time necessary for planning the project itself. You will have to find a style that works best for you, but I don't think you can accurately schedule a project until you know the topics and features the online help system will contain. You won't know this information until the end of your project planning. I therefore present information based on scheduling tasks at the end of project planning. 28 Different help authors also have different opinions on how you should allocate time for tasks. I've heard some theories that state you should take the total time for all of the tasks and multiply it by a number, such as 1.5 or 2, to account for unknowns that may come up during the project. Again, you have to find a system that works for you, but I don't believe in multiplying times by arbitrary numbers. Instead, I believe you should predetermine the different setbacks you might face during the project and account for them in your schedule. In general, you should consider the following issues when setting a task schedule: Time required to write and edit help topics, create images, develop multimedia files, and create any other supporting files These tasks should be your largest consideration. They make up the bulk of your project and therefore dictate, for the most part, how long the project will take. Many help authors use a formula to determine the amount of time it takes to research, write, and edit each topic in a HelpSet. They usually calculate approximately four hours per conceptual or procedural help topic and approximately one hour per field-level help topic. Using a formula like this is acceptable to calculate an estimate when you have no other information with which to plan, but you must remember that this is only an estimate. The more intimate you are with your software and the more aware you are of the tasks required to develop the HelpSet(such as creating images and multimedia), the more accurately you can calculate the number of hours for each help component. Number of personnel working on the online help project and their experience levels Your project may or may not proceed more quickly if you have more people working on it. You must also consider the experience level of the people working on the project. Having experts for each type of component(such as images and multimedia) increases the speed of development. On the other hand, using interns or entry-level personnel can decrease the speed of development. Time required to learn new software If you plan to use new software to write help topics, create images, create multimedia clips, or perform other tasks, you must keep in mind the time needed to learn the new software. As you become familiar with JavaHelp, you will notice an improvement in development time. You also should consider the time spent to troubleshoot problems or contact customer support if you must resolve issues with the new software. Time to test the finished online help system You must build in time for testing the online help system and its components. The amount of time you estimate for this task depends on your resources. Some companies have quality-assurance personnel who are experts at testing software. Other companies require help authors to test their own systems. When you plan for testing, be sure to account for all components of the help system, such as the navigation components and multimedia clips. You will probably be more successful if you schedule testing concurrently with development. Time to integrate the online help system with the software application Once you have a functioning help system, you have to connect it to the software application. This process can be time-consuming; it depends on the presentation option you choose. If you include a single button to launch a standalone Help Viewer, it won't take much time to make the connection. However, when developing context-sensitive 29 help, you must include the time it takes to assign each help topic to a specific object within the application. Deadlines set by project leaders or other team members Often, help authors are not allocated enough time to develop a good help system. Project deadlines and other project-related constraints pose certain obstacles to scheduling. In such cases, you must determine which tasks you are willing to sacrifice and settle for whatever help system you can best create in the limited time. 3.2 Planning Tasks Specific to JavaHelp 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. 3.2.1 Deciding How to Present the HelpSet 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. 3.2.2 Deciding How to Install the HelpSet 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: • For an independent Java application, images work well, but you should put multimedia files(depending on the number of files and their size) on a CD-ROM. • For applets or applications that run on a local network, include images and multimedia clips on the network server. • For applets that run in a web browser(assuming users connect with a modem), minimize the use of images. Multimedia clips are generally not feasible unless you can use 30 streaming, a multimedia technology in which users can start viewing a multimedia clip before the file has completely downloaded to their computer. 3.2.3 Outlining the File and Directory Structure The preceding chapter included a brief presentation of a HelpSet's file and directory structure. Since topic-to-topic links depend upon the correctness of relative URLs, it is worth outlining the entire directory and file structure before writing individual help topics. Keep in mind that third- party help-authoring tools(discussed in Chapter 9) can help organize your project directory and file structure. The first directory you must create is the main project directory, in which you place all other project directories and files. Name this directory after the application for which the help is written. For example, for the sample word processor application used earlier in this chapter, the main directory is named Word-ProcessorHelp. Figure 3.2 shows the directory structure for the WordProcessorHelp project. Figure 3.2. Directory and file structure for a JavaHelp project You might use a modified directory structure if you plan to merge different HelpSets. These considerations are discussed with the information on merging HelpSets in Chapter 6. 3.2.3.1 Structuring HelpSet data and navigation files When you outline your file and directory structure, keep in mind that all JavaHelp files refer to each other by their relative positions to one another: • The HelpSet file refers to the map file and the navigation files(TOC, index, and word- search index). • The map file refers to all the help topic HTML files. For example, a HelpSet file might refer to the map file like this: 31 The filename Map.jhm, with no directory location, indicates that the map file is in the same directory as the HelpSet file. I strongly suggest that you keep the HelpSet, map, and navigation files in the main project directory. The files reference each other by filename only, without having to specify any directories. 3.2.3.2 Structuring topic and field-level help directories and files All topic directories and files are listed relative to the location of the map file. For example, the map file from the preceding chapter includes these lines: The directory Topics, along with the subdirectory Interests and file Computers.htm, is listed relative to the map file: the Topics directory is at the same directory level as the map file. I strongly recommend having one major Topics directory at the same level as the map file, as illustrated in Figure 3.2. Notice that I placed the FieldLevelHelp directory outside the Topics directory. You usually have the word-search index utility search the entire Topics directory to build its search database.(I discuss this utility in Chapter 5.) Excluding the field-level help files from that directory means they won't show up in any word search. If you want to include field- level help in the word-search index, place the FieldLevelHelp directory under the Topics directory. Alternatively, add the topics to the search database manually, as discussed in Chapter 6. 3.2.3.3 Structuring images and multimedia files The main project directory should also have directories to hold any images and multimedia files. Figure 3.2 show Images and Multimedia directories. As with each of the topic directories, use these directories to store files as you develop them throughout the project. 3.2.3.4 Structuring pop-up and secondary window files A final consideration when outlining your file and directory structure is whether or not you want the JavaHelp system to display some your HelpSet's topics in pop-up windows and secondary windows. As discussed in Chapter 6, pop-up and secondary window topics are simply HTML files, just like the rest of your topic files. However, you should consider storing these files outside your Topics directory for two reasons: • You will find it easier to stay organized if you keep pop-up and secondary window files in their own directories. • You will probably want to exclude pop-up and secondary window topics from the word- search index. Therefore, as with the FieldLevelHelp directory, you should place these directories outside of the Topics directory. 3.2.4 Planning the Navigation Components Planning for your navigation facility depends on the size of your HelpSet and whether or not you use a third-party help-authoring tool to create it. If you use a third-party tool, the time to create the navigation facility is negligible—since the third-party tool does the work for you. If you create your HelpSet manually, you should plan on creating the navigation components as you write the online help topics. Add enough time to your schedule to add each topic to the TOC and index, 32 keeping in mind that there will probably be several index entries for each topic. You shouldn't have to plan too much time for the word-search index, since JavaHelp includes a utility for generating it. 33 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 4.1 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 4.1.1 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. 34 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. 4.1.2 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. 4.1.3 Obtaining Approval from Team Members 35 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. 4.2 Creating Help Topics and Applying Appropriate HTML Tags 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. 4.2.1 Naming the HTML Files 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. 4.2.2 Applying Formats to Text 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 36 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. Figure 4.2. Displaying formatted text Here is the source text for the topic shown in Figure 4.2; it uses standard HTML formatting tags: Formatting Text

Formatting Text

You can use the following text formats with the word processor:

  • bold
  • italic
  • underlined

Use the following steps to apply text formats:

  1. Highlight the text that you want to format.
  2. Click Format from the Edit menu.
  3. When the Format window appears, click the appropriate text format.
  4. Click OK.
This text uses the following HTML formatting tags: •

identifies the topic title. You can use

and additional heading levels throughout the help topic if you want to break it down into subsections. •