Re: API documentation

["Steven J. Owens" <puff -at- netcom -dot- com>]

Barbara Hubert writes:

> The  product is a Java-based technology (Development toolkit). The
> target is to enable someone with, for example  a first year Java
> programming course, to be able to build apps with this development
> toolkit.
> 
> The questions:
> 
> 1.    What delivery format is preferred for this type of documentation
> (linear, online, cd)
> 2.    Is anyone aware of any internet resources that would assist me in
> putting this documentation together.
> 3.    Any other relevant advice would also be welcome.

     Javadoc is the format for API docs, it allows the API to be
documented by comments in the code (which makes it easier for them to
be kept up to date).  The javadoc tool then generates HTML pages from
the API tags in the source.  This is the technology used to maintain
the online docs for the java class libraries.  It's your best starting
point for this project.

     As for format, searchable online is a must.  Printed is handy as
well (since screen real estate is precious) but if you can only have
one, have searchable and printable online format.

     You can find more information on javadoc at java.sun.com.

     The place javadoc (and the java class library api docs) falls
down is with more overview-oriented topics.  Specifically, the javadoc
tool generates a hierarchy of HTML files, but cross-linking between
items is nonexistent.  Essentially what it lacks is the context, the
flow of events, that will help the reader understand how the system is
supposed to work and to be used.

     I'd strongly suggest you also include UML class diagrams and
scenarios, and perhaps use cases.  A good starting point for learning
UML would be Martin Fowler's _UML Distilled_.  From a design/aesthetic
standpoint (not to mention simple visual usability) I think UML sucks,
but it is emerging as the dominant standard in the Object Oriented
field, so use it.

     Start there, but don't stop there.  The reference information is
criticial, supplemental "sideways" information, context, is needed as
I noted above.  Add overviews of how the classes are used, UML diagrams
and scenarios, use cases, etc.

     But, examples, well commented, detailed, with working code, are
probably your best bet.  Ask any dozen programmers what they want the
most out of a document and they'll tell you, lots and lots of
examples.  Odds are, quite likely neither you nor your engineers are
qualified to generate good examples.  You're an expert at
documentation, your engineers are experts at the underlying software,
but neither of you have enough exposure to the everyday working
conditions of the code.

     I ran into this a lot, back when I was writing database developer
and administrator guides.  It was like moving heaven and earth to get
an actual DBA in to look at things and tell us what would and would
not typically be expected of the DBA.  My suggestion, if you can pull
it off, is to get a handful of your target market developers - the
guys and gals who'll be using this API - in a lab with you, your
reference docs and UML diagrams, maybe a product trainer, and your
developers.  Make it a collaborative exercise to develop five highly
detailed, realistic projects using the API.  Use the results in the
docs.

     The customers get a first look at the product and a chance to
talk with the engineers who developed it (most customers would kill
for such).  You get excellent, realistic, detailed examples.  Your
engineers get feedback from real end users.  Everybody's happy.

Steven J. Owens
puff -at- netcom -dot- com