Are you being asked to deliver more and more documentation, including help content, for the applications you develop? If you answered yes, you’re not alone. More than 55 percent of members who responded to a recent survey indicated that they write help files for the applications they build. Sure, you may still get some help from a technical writer. But programmers who also write fairly well are commonly called upon to pull double-duty by authoring and implementing help files.
Sun's help format, JavaHelp, can make the job a little easier for Java developers as they create on-screen user support. Sun JavaHelp is a help format developed fully in the Java programming language, written to work with your Java applets, JavaBeans components, and applications to deliver useful information to users.
Help authoring tools that support JavaHelp
- Brown Inc.’s HTML Indexer
- eHelp’s RoboHelp Office
- MediaMix Technologies’ HelpStudio
- Quadralay’s WebWorks Publisher
- Solutionsofts’ HelpBreeze
- WexTech System’s Doc-To-Help 2000
What you need to get started
A standard extension of the JDK, JavaHelp 1.1.2, the most recent version, is available for download from Sun. To get started, developers need both the JDK and JavaHelp. Users’ systems need the Java Run-time Environment (JRE) 2.1 and the JavaHelp components to launch JavaHelp files. JavaHelp works with an HTML-based viewer, using HTML 3.2 and XML to present help content in a format that includes content and navigation panes and a toolbar. There’s no licensing fee for the technology.
As a pure Java tool, the cross-platform JavaHelp format offers a level of flexibility that makes it worth considering. Help files can run on Windows, UNIX, Linux, and Mac operating systems. You can write your help system to be either client- or server-based, although Sun promotes the spec as being “ideally suited for the network.” Files can be encapsulated and compressed into a single Java Archive (JAR) file or can be delivered uncompressed in multiple files. You can even deliver the help embedded within your core application or as a stand-alone applet.
With JavaHelp, you can develop contextual help that is available to users at the window, field, and help button levels. The system identifies help files as URLs. For complex applications that require more features than the standard set, you can customize the help presentation options—provided you have the time to do so, of course.
Developing files to be used with an internationalized application should also be fairly easy in the JavaHelp spec. Localized counterparts would need to be translated in the proper language, and browser support for the particular locale should be thoroughly tested. The JavaHelp System’s User Guide includes a nice amount of detail on localizing your help system.
How is it done?
While a variety of well-written help authoring tools have simplified the process of preparing online help content, including compressing files in the proper format, developers don’t need a lot of third-party help to work in the JavaHelp spec. The steps are straightforward:
- Create the help files, including the HTML topics, helpset file, the map file, the TOC, index, and content files.
- Create the search database using jhindexer, JavaHelp’s command-line tool.
- Compress the files into a JAR file.
- Add the help to the application by creating the helpset, defining the ID strings, and setting up the components.
- Use the hsviewer command to display your helpset.
For guidelines on how to develop a good JavaHelp help system, check out Creating Effective JavaHelp, by Kevin Lewis, published by O’Reilly.
JavaHelp seems to be emerging as the standard delivery spec for Java applications, with widespread support from third-party help authoring tools. However, the spec has some limitations, including:
- Partial support of cascading style sheets.
- Some problems with display of pop-up windows.
- Occasional image distortion, depending on which version of Swing your application uses.
A known bug listed by Sun forces you to specify tag names in styles and style sheets using lowercase letters, or they will be ignored. JavaHelp systems running in applets must be run on Web browsers using JRE/JDK 1.1.6 or later with the Java Plug-in. Support for framesets is not provided. Of course, over time, Sun likely will deal with these issues and make JavaHelp as robust a tool as some of the Windows-based help specs, which have had several years of refinement.
The development spec is just one aspect of creating a successful help implementation. In my next article, I’ll discuss what developers can do to facilitate development of help functions when a technical writer is on the team, and I’ll provide a list of downloads to simplify the process.