15
Tue, Oct
6 New Articles

Java Journal: Help with Help or How I Learned to Stop Worrying and Love the Help System

Java
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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 This email address is being protected from spambots. You need JavaScript enabled to view it. and let me know what you would like to see covered in upcoming columns.

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 This email address is being protected from spambots. You need JavaScript enabled to view it..

Michael Floyd

Michael J. Floyd is the Vice President of Engineering for DivX, Inc.

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More 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.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY 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.

  • SB HelpSystems ROBOT GenericForms 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.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA 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:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA 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.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra 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: