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.
JavaHelp
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.
Helpsets
JavaHelp uses the notion of a helpset to encapsulate the help system. The helpset itself consists of the following entities:
-
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?
Helpset Viewer
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.
Integration
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.
Going Global
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.
Flexibility
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.
Shortcomings
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).
Conclusion
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
Although it hardly seems possible that two years have come and gone, "Java Journal" is marking the completion of its second year. We have covered a lot of topics in the last year, and I look forward to bringing you even more next year. JavaOne is just around the corner (June 28 to July 1 at Moscone Center, San Francisco), which means that new Java technologies are bound to follow. In my premier Java Journal column, "Let's Get Started with JavaWeb Start," and in last year's first annual anniversary column, "Web Services Developer Pack JAX-RPC," I stated that this column really is for you the reader and that I want all of you to let me know what you are most interested in. I really do listen and tailor my topics to your requests. Your suggestions have helped me understand what topics are most important to you. So drop me an email at
Michael J. Floyd is the Software Engineering Manager for DivXNetworks. He is also a consultant for San Diego State University and can be reached at
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online