What this documentation sample illustrates

Documentation sample: AVSapi.pdf

My custom javadoc doclet

  • I subclassed Sun’s Doclet library so that I could run javadoc against a client’s Java code and get custom output. This document, a FrameMaker document matching the client’s FrameMaker template, was almost entirely created by my custom doclet. I illustrated to the client how I could create 1200 pages of skeleton API documentation from their Java code in a day or so, saving them at least 3 weeks of typical technical writer typing and enabling their writers to focus on the area of real value: meaningful descriptions.

  • javadoc can still be run normally, enabling the customer to generate HTML API documentation.

  • It improves on the standard javadoc in many ways. Here are a few:

    • Method detail sections are sorted alphabetically.

    • Headings for methods include parentheses and arg datatypes (especially helpful in distinguishing overloaded methods).

    • Incorrect or missing javadoc tags are revealed. For example, my doclet creates a placeholder for every method parameter. If the comment writer has omitted or mistyped a @param tag, a [[bracketed]] flag will be added to the document.

An API documentation style

  • This client needed someone to create new API reference documentation and propose how to repair legacy API reference documentation. I proposed this style and they were delighted.

  • This is consistent with the style I teach in my courses for technical writers on "Documenting API for a Developer Audience." It draws from the best of styles I have encountered. It picks up many of the good characteristics of javadoc-style API documentation (with which many developers are familiar) while making up for several deficiencies in standard javadoc output, as noted above.

How I work with developers

Where I need information from developers, I bracket my [[questions]]. On a printout, I highlight and number the items and make a copy for myself. The developer can address the questions via email (answering by number) or in person.

A fraction of the solution

While it may be fitting to insert brief "how to" information in API reference documentation like this (for example, in the class or method description), it may be best to provide a separate API usage document, one which helps the reader understand when and how to use which classes and their members—more of a philosophy and sequence discussion than simple reference.

API reference and usage documentation is but part of an overall documentation package. Such a package may include installation instructions, a user guide, configuration details, discussion of architecture and instructional material, such as a tutorial.

John E. Darrow