Re: API style guides?

[Jason Huntington <JasonH -at- CAPTURA -dot- COM>]

Of course, APIs can be as small as a few functions or as long as your
arm.  I always look for ways to automate collection and formatting of
information for long API references.  Automation becomes especially
helpful when functions, methods, or variables change and you have to
maintain the API reference.

A prime opportunity for the enterprising tech writer assigned to write
an API reference is to improve the quality of descriptions of elements
such as classes or objects.  I like to provide developers guidance in
the form of a code commenting guide including lots of examples.
Automation helps at this stage too so that you can extract (and in some
cases such as using JavaDoc, format) the contents of your reference
repeatedly without having to start from scratch each time.

I agree that the best course for deciding how much and what kind of
information to include in an API reference is to listen to a programmer
or project architect and to consider the audience.  Your general sense
of good online style is applicable to API information.  A little more
jargon than usual is allowed or even required when you consider that
your audience should already be well versed in the essentials of the
programming environments involved.

In a major project for a large network software company making their
first Java application, we decided on two online books.

*       The Developer's Reference included an index to classes, methods,
and variables and, for each class, a complete discussion of the work the
class was expected to do in the system, pictures and diagrams, and an
alphabetical listing of the public methods and variables belonging to
the class.  I liked to compare the reference to a dictionary of the
program-an aid to someone ignorant unsure of vocabulary specific to the
implementation.

*       The Developer's Guide was task-oriented, a sort of How To for
developers who wanted to extend the program or use advanced features.  I
liked to compare the guide to a grammar of the program-and aid to those
who wanted to use the implementation in conversation, as it were.

We used a tweaked version of JavaDoc to extract comments and code
elements from the class library and build a document consisting of
linked HTML pages.  The work of commenting and marking up comments fell
to each developer.  I acted as an HTML and style consultant and the
editor who periodically ran a .BAT file to build the reference document.