Most programmers, including me, hate doing documentation. Whether it is updating UML diagrams to reflect "as-built" specifications or putting comments in their code to help future generations figure out just what they were trying to accomplish in the first place, documentation probably ranks just below everything except status reports on the "what I would most like to do" list. The most loathsome of all documentation tasks are those that are the most user-centric. Whether it is the help system or user guide, there is a reason it gets left until the end of a project. After all, do we really need to do a user guide? Didn't we spend an excruciating amount of time making everything in our user interface intuitive? Well, we would all like to think this is true, but in the real world, people have questions and expect, or at least hope, to be able to find answers in an application's help system. So in spite of our best efforts and reluctance, help systems are compulsory. So if we have to create help systems, let's use every tool available to us to make the process take up as little of our time as possible. That way, we can get back to creating intuitive user interfaces.
In a simple application, it's trivial to roll your own help system. All you have to do is create a button or two, throw some text in a window that pops up when the right buttons are pressed, and you're done. However, most applications are not trivial, or they start out being trivial and grow into something more complex. Here's where JavaHelp comes in. JavaHelp is a collection of APIs that does all of the tedious parts of a help system for you. JavaHelp provides navigation, table of contents, indexing, full text search, and localization support. In addition, JavaHelp lets you customize how and where you display help and compresses and encapsulates the help system itself. It also lets you merge help systems, do dynamic updates, and even customize your help system by swapping in your own search engines or other components. JavaHelp is an extension to the standard Java 2 Standard Edition (J2SE) platform and is provided at no cost by Sun, who also grants you the rights to freely redistribute it within your applications.
As of the writing of this article, the current version of JavaHelp is 2.0 and can be downloaded from Sun's JavaHelp download page. You can also get additional information from Sun's JavaHelp home page. The download is packaged as a zip file that you can decompress and put wherever you like to store your Java extensions. The bundle includes several full-featured examples that you will want to work your way through after familiarizing yourself with the overall architecture of JavaHelp.
The helpset file--an XML file with an .hs extension. The helpset file contains the location of the mapfile as well as metadata describing which navigators should be included and optionally any sub-helpsets and presentation parameters.
- Topic files--HTML files, one per help topic.
- Map file--an XML file with a .jhm extension. The map file contains a list of topic IDs and their associated URLs.
- Table of Contents (TOC)--an XML file with an .xml extension and the letters "TOC" in the file name by convention. The TOC file contains a mapping of Table of Contents entries to Help Topics and is displayed in the Table of Contents navigation tab of the help viewer.
- Index--Like the TOC, the index file is an XML file with an .xml extension and the letters "Index" in the file name by convention. The index file contains a mapping of key words to Help Topics and is displayed in the Index navigation tab of the Help view.
- Full text search database--a collection of files generated by the jindexer tool to help you do natural language searches across your help system. These files are never accessed directly by the user or programmer.
All of the files that constitute a helpset can be encapsulated into a single .jar file for easy distribution with your application. In addition to providing encapsulation of your help system files, storing them in a .jar file (which is a special type of .zip file) also provides a significant amount of compression. This may not seem that important to most applications, but just wait until your company decides to localize your product into 20 different languages; even the lightest help system will take on an awkward weight. Also, because the locations of help topics that are stored in the map file are URLs, the topic files themselves can exist either locally in the .jar file or anywhere on the Internet. Likewise, since the location of the map file itself is addressed by a URL on the helpset file, it too can be either local to the .jar file or anywhere on the Internet. Being able to distribute your help system in this way allows for great flexibility. If your product has a static help system, it can be deployed with the product. If your product has a dynamic help system, it can be put on a Web site. However, a mixed approach is also possible: The core functionality is stored locally, and dynamic information such as FAQs or known issues are stored on a Web site. How and where to partition your help system is up to you and is totally transparent to the users, provided they have a network connection.
So you need to consider these issues when determining how to deploy your help system:
- How dynamic is the help information?
- Do the users have Internet connections? Do they need to be able to access help when offline?
- How large is the help system? Will you pay for less bandwidth by deploying it all locally or by serving it from a Web site?
The helpset viewer is a Java application distributed with the API that lets you browse the contents of a helpset exactly as they will be seen from within the application. In other words, you can view individual help topics, switch topics using the TOC, or find keywords using the index or full text search functionality. The helpset viewer is a great tool for the authors of your help system to use to see what the help system will look like even without the context of having an application to launch it from. In this way, we can decouple the application and the help system so that they can be worked on simultaneously and independently. In fact, because helpset can be easily merged, you can have multiple help authors, each working on separate parts of the help system.
Tying the help system into your applications is trivial. After some initial setup, all you need to do is add one line of code to request that a certain topic ID be displayed. From then on, the help system takes over.
Whether you call it internationalization or localization, JavaHelp supports it. For all the gory details of how you implement help systems in other languages, see chapter 6 of the JavaHelp API documentation. However, from a more abstract level, think about it this way: Everything we've done up to this point--with the exception of the full text search files--have been stored in either HTML or XML, so all we really need to do is clone our files in another language and add something to the namespace that lets us know which language a given group of files is associated with.
As if all of this wasn't overkill already, JavaHelp provides some additional features. You can create pop-up or secondary windows anywhere in your help system. There is even a separate mechanism for contextual help. You can define your own help viewer and make it external to your application or embed it right into existing windows. If you don't like the full text search engine, you can either integrate into a third-party search engine or roll your own. If you are not happy with the Table of Contents, Index, or Full Text Search navigation panels, you can write your own navigation panel. Nearly everything in the JavaHelp system is abstracted behind an interface, so if you need to extend or customize, all you need to do is implement the interface.
Help Authoring Tools
Chances are good that the authors of your help system are not HTML or XML experts, and although these are not difficult file formats to master, it is still probably better to provide them with authoring tools that generate all of these files and keep them in sync. Sun has a list of third-party JavaHelp Authoring Tools on its Web site.
Actually, I have found the package to be rather useful and complete. The only item on my wish list is that the help system not include hint text (the micro help windows that pop up when you let the mouse linger on a particular control).
One of my favorite books is The Pragmatic Programmer: From Journeyman to Master by Andrew Hunt and David Thomas. In it, Hunt and Thomas devote an entire chapter to the power of plain text. The JavaHelp system is a testament to this truism. Through nothing more than plain text files (HTML and XML) organized and zipped together as a helpset, an entire help system can be built. JavaHelp is both elegant and flexible, letting you tailor your deployment to your requirements. It is very complete but still allows you the flexibility to extend it if needed. The API comes with tools like the HelpViewer so that help authors can work independently from developers. It also comes with the jindexer tool that builds a natural language search database for you. Integration of the help system into your applications requires very little programming, and the help system itself is decoupled from the application such that it can vary completely independently from the application itself. To accelerate the actual writing of your help system and to ensure continuity, you might want to consider using a third-party authoring tool. So stop worrying about your help system and get it done so that you can work on something more fun.
Java Journal's Second Anniversary