Java Software Product Documentation
This is a collaboration about the issues involved in creating documentation for Java software products. It began as correspondence between Bill Albing and Matthew Arnold Stern and includes a bit from Rick Sapir, too. Feel free to add to this. You can join this collaboration or post a comment if you are a registered user.

Contents:

Background

This material assumes you are familiar with Java software and want to know more about how to provide good Java product documentation with the software product. For beginners, you should acquaint yourself with these:



General Java Documentation Issues


Selecting an IDE to use and a version of JDK

In terms of which integrated development environment (IDE) to use, many of us use NetBeans 3.6, but 4.0 is available. The file system interface is different in the two versions. In going from 3.6 to 4.0, NetBeans changed their file management a system based on ANT scripts. The user interface (UI) is different, but not hard to figure out.

Use the automatic comment tool, Tool > Auto Comment, to help automate the process of filling in the necessary summary comments and parameter descriptions, etc.

Some development teams are switching to Eclipse because it is easier to set up projects.

In setting up your development system, a more critical item to consider is your version of the JDK. If you use the new one (5.0), some doclets will not work. That's why I stick with JDK 1.4.2. NetBeans 4.0 and Eclipse will work with either JDK 5.0 or 1.4.2.

Selecting automatic generation tools


For automatic generation of the API reference, you can use Javadocs or any number of tools. For JavaHelp, there are several tools out there. Refer to http://javatoolbox.com for a summary of tools.

Excluding files, classes, or members from Javadocs

For the automatically generated docs using Javadocs, how do I exclude some of the methods or interfaces if they are "internal use only"? They're public but I want to exclude them from the docs. How best to do that? Is there a way to filter out the ones that have a certain comment or certain tag? And can I exclude a whole file from Javadocs? What do you do?

You can specify the package and file names to include with the Javadoc command. In the mifdoclet example I showed at the conference, I generated Javadoc for only one of the two packages in the NetBeans Anagram Game example.

I don't remember if in NetBeans 3.6 if you can specify which packages to include in the Javadoc. I know with NetBeans 4.0 that you can't do it through the UI. You would need to modify the ANT build script or create a batch file to generate Javadoc from the command line.

The Javadocs page says you can't do individual members, but you can leave out files and that excludes the contents of the file. See more about excluding.

Creating printable equivalents

For the other product versions, we create both a compiled help system file and a PDF file (for printing). For Javadocs, and for my JavaHelp set, how should I provide a PDF of the same docs? Do you deliver PDFs?

The MIF doclet can generate PDF directly as well as FrameMaker MIF files. Some other doclets that can generate PDF files directly are AurigaDoclet http://aurigadoclet.sourceforge.net/ and PDF doclet http://sourceforge.net/projects/pdfdoclet/, but I haven't tried these.

See the Javadocs pages for more information on printing.

Deciding on deliverables

I was creating a help set using JavaHelp (which takes HTML and sort of compiles it like the compiled help I'm working with on the Windows platform. Have you used JavaHelp at all? Would I still be able to use both my HTML files that I created by hand as well as the auto generated files using Javadocs? Just curious how that would all work.

We deliver only HTML files. We chose that format because it is the most familiar to Java developers, and because this is a server-based product, there isn't a concern about the number and size of files. I haven't used JavaHelp. You can use the HTML pages you authored separately with the generated Javadoc. You can provide links from your pages to the Javadoc, or you can host the Javadoc pages in your frameset, as I showed at the conference.

Putting Javadoc and JavaHelp together in one deliverable


Refer to Integrating JavaDoc (API Reference) with JavaHelp (Online Help): Two Approaches by Rick Sapir, elsewhere on this site.


There is no single convention, but you can edit the HTML (using a Web site development tool) to allow group search and replace to insert company name, copyright, or logo in the footer or header of all the files. Typically, another cell can be added to the header nav(igation) table and the same cell added to the footer nav(igation) table, which includes the company name and product name and version. A separate line at the bottom of the HTML page, beneath all the tables, can contain the copyright statement. This is a start. I also add a paragraph on the overview-summary.html page before the table of packages that includes a brief description of the product and a trademark after the product name. On this page, at the bottom, I add a fuller legal description of trademarks and copyright. I also add a link to a generic docs email address at our company for feedback to the doc team.


Understanding the "Deprecated" section in Javadocs

What if nothing is deprecated? Should I remove it? (more content coming here soon)
The deprecated section is for members in code that have the @deprecated comment tag to indicate that it is still available for backward compatibility in this version but that the functionality has been replaced with something newer and better.

Editing the "Help" section of Javadocs

There is a file, help-doc.html, that you can edit and add information that is specific to your Javadoc API help pages. (more content coming here soon)


Adding a "search" capability to the Javadocs (so that it has all the functionality of a help system)


If you are delivering only Javadocs (i.e., a set of HTML files), you can use any of a number of third-party search tools to add a search engine. Some require ASP or CGI; others only require a Javascript-enabled browser.

Then simply add a button or link to access the search page.

Rick: If you are delivering a JavaHelp or OHJ helpset:
1. Run the jhindexer (JH or OHJ) against the Javadoc HTML files (simply select the full directory) to generate an IDX file.

2. Create a helpset HS to contain the Javadocs. It can be as simple as:
<helpset>
<view>
<type>oracle.help.navigator.searchNavigator.SearchNavigator</type>
<data engine="oracle.help.engine.SearchEngine">search.idx</data>
</view>
</helpset>

3. Add the Javadoc helpset as a subhelpset to your "main" help system:
<subhelpset location="javadoc/javadoc.hs" />


Showing example code, if at all

Most projects that I see out on the Web have incomplete documentation and none of them show example code snippets. Doesn't anyone include example code at the level of the individual method or interface?

Matthew: We don't provide code snippets for every method, property, and event. We provide examples of performing specific activities, such as initializing a connection to a server or retrieving information from a database. We also maintain the samples as separate Java files and describe in the SDK documentation where to find the files. The reason why we make the files separate because developers can change them up to the last moment. If we also include them in the documentation, those samples can get out of sync.

See the Javadocs pages for more information on examples.


Finding more information

To see the Javadocs that others have created, do a search of the Web with a search engine with the following string:

Overview Package Class Tree Deprecated Index Help PREV NEXT FRAMES NO FRAMES

since those words are always in the Javadocs. Most of the sites it returns are on sourgeforce.net, but there are others.

Rick: Most venders make Javadoc available on the internet. Here's just a few examples:

Copyright © by Bill Albing and Matthew Arnold Stern. Some rights reserved.

Examples and Demos

Rick: Here's a quick demo that I put together showing:
  1. Accessing Javadoc (context-sensitive) from an IDE.
  2. Displaying a "snippet" of Javadoc (again, context-sensitive).
  3. Integrating Javadoc API with your online help deliverables.

This demo shows the current (non-vaporware) deliverable Oracle JDeveloper 10g 10.1.2.

Making Java-based Help Do More

I've been documenting with Java-based software applications for several years. Creating help systems and online-deliverable documentation is a challenge for several reasons:
  1. Until recently, few HAT (help authoring tools) vendors provided Java-compatible outputs.
  2. Most traditional formats (CHMs, WebHelp(tm), etc.) rely on extensive scripting or APIs that are not available in Java.
  3. Depending on your interpretation, using a HTML, browser-based output (such as HTML help) may violate the Java security model and therefore not be a valid choice for delivery

In addition to discussing how to make your Java-based help systems do more, I've also included a In the Real World section for each feature that explains why the feature is useful and demonstrates my implementation in a real product.

Java-based Help Systems

  • JavaHelp (JH) — The Java-based help system from Sun (http://java.sun.com/products/javahelp/). JH uses Swing to render the HTML pages in a Java applet. However, the JEditorPane Swing component does not fully support HTML4.x.
  • Oracle Help for Java (OHJ) — Java components and an API for developing and displaying HTML-based help content in a Java environment from Oracle (http://www.oracle.com/technology/tech/java/help/index.html). OHJ uses a third-party browser from ICESoft to render the HTML pages and fully supports HTML4.x and CSS2.x

Features

Both JH and OHJ support many of the online features that both users and authors have come to expect, such as:
  • Dynamic table of contents
  • Full-text and boolean search
  • Expandable, customizable API
  • Pop-ups and cross-links
  • Context-sensitive support (such as What's This? help)
  • Cross-platform support
  • Localization support
  • Favorites and bookmarks
  • JAR compression

Table of Contents

In JH and OHJ, the Table of Contents (TOC) is controlled by an XML file (such as toc.xml).

Custom Images

By default, JH and OHJ use No image specified. One of the following parameters must be set: fileId, randomGalleryId, fgalId, attId, id. and No image specified. One of the following parameters must be set: fileId, randomGalleryId, fgalId, attId, id. (respectively) to show expanded/contracted TOC elements. In some instances, however, it is helpful to use a different icon to represent different items.

For example, consider the images in the TOC from Microsoft WordPad:
Figure.1
Figure.1

In addition to the usual opened, closed, and topic images, the author used two additional icons to designate different types of information:
  • Overview
  • Common tasks

To accomplish this in JH or OHJ:
First add the target and url of the image to your map.xml file:
<mapID target="nameOfImage" url="images/myImage.gif"/>

To add the image to the TOC item, use the image attribute in your toc.xml:
<tocitem target="filename.html" text="Some Heading" image="nameOfImage"/>

Figure.2
Figure.2


In the Real World
Figure 1 shows a simple example. But what about a more complex use case?
....


When users click on an element in the Table of Contents, the help system can take one of three actions:
  1. Open the link
  2. Expand the TOC element to show its children
  3. Both open the link and expand the element

To simply open a content page when users double-click an element in the TOC, create a tocitem element with both target and text attributes in your toc.xml file:
<tocitem target="somePage.html" text="My Heading Text" />

Be sure to add a mapid for the somePage.html target in your map.xml file

Clicking not the My Heading Text entry in the TOC opens somePage.html in the content page.

Expand Element

Sometimes, a TOC element is simply a "container" used for organizational purposes.
To create a TOC element that simply expands to show its children elements, create a tocitem element without a target:
<tocitem text="My Heading Text">
<tocitem target="somePage1.html" text="My Subheading" />
<tocitem target="somePage2.html" text="Another Subheading" />
</tocitem>

Be sure to add the necessary mapid for each tocitem target in your map.xml file

Clicking not the My Heading Text entry in the TOC displays the next level of TOC items (My Subheading and Another Subheading) but does not open any file in the content page.

Notice also, that in this example in toc.xml, the tocitem element requires a closing element, because it contains sub-elements.

Figure.3
Figure.3


If your "container" TOC element has actual content, you'll want to both open the content page and expand the element to show its children. Similar to the Expand Element example, but we'll include the target element as well:
<tocitem target="somePage.html" text="My Heading Text">
<tocitem target="somePage1.html" text="My Subheading" />
<tocitem target="somePage2.html" text="Another Subheading" />
</tocitem>

Figure.4
Figure.4


In the Real World
....


Custom Navigators

By default, OHJ provides the following navigators (tabs)
  • TOC
  • IX
  • Search
  • Bookmarks (JH 2.x) / Favorites (OH 4.2.x)
  • Glossary (JH 2.x)

However, you can create additional tabs simply by expanding the view element in the HS (helpset) file.


....


Deploying Locally or Using Web-delivery



Integrating With Documentation (aka Single Sourcing)

Many HAT vendors provide direct support for producing both JH and OHJ deliverables. Both Sun and Oracle maintain third-party lists.

Additionally, Oracle offers a HelpSet Authoring Wizard that allows you to convert existing HTML files to OHJ, without requiring a specific HAT.


Samples







Return to the list of Key Collaborations.


Contributors to this page: Bill Albing , Rick Sapir and Chief Editor .
Page last modified on Monday, October 08, 2007 01:56:37 pm EDT by Bill Albing.

Key Pick New

Bill Albing has some suggestions to improve STC competitions. Read and let us know, what do you think?

Other Key Picks... Read more

About KeyContent

About KeyContent
KeyContent.org is an idea space where you can express your insights about your profession. Think of this site as a white board with a brain. You create and edit articles or portals to other sites and share your insights... Read More


Key Ads

Key Connections

Join KeyContent on these networks:



Key Products

Make Custom Gifts at CafePress

Key Promotions