API documentation with references to Javadocs documentation

[Emily Berk]

Hi Ron:

I do sets that include both javadoc and API guides in FM/PDF all the time.

The way I think of it is that the javadoc is a complete reference to 
the public API, kind of like a dictionary of all the classes and 
methods.  The FM documentation is more like an encyclopedia.  I 
usually call it a Developer's Guide.

The FM documentation highlights the most important classes and 
methods, but maybe doesn't mention all the nuances of each (like, 
maybe it doesn't go into great detail about every parameter passed to 
the method).

On the other hand, the FM documentation includes more general 
material not easily incorporated into the javadoc, such as the order 
in which methods ought to be called or guidelines about when to use 
one technique (set of classes/methods) vs. a different technique to 
implement particular use cases.

To x-ref from the FM doc to the javadoc in the context of a section 
that discusses a particular class or method, I just say, "For more 
information, see the javadoc."  A developer ought to know how to go 
about finding a class or method in the javadoc.  (Of course, you also 
need to make sure that the class/method is actually documented in the javadoc.)

Hope this helps.

-- Emily

At 10:46 AM 5/13/2008 -0400, Ron Miller wrote:
>Hi:
>I have a JavaDocs reference. My client has asked me to write an API
>document in Frame with references to the JavaDocs documentation. The
>goal of the document is to provide further explanation and examples
>along with a context for usage beyond what is provided in the
>JavaDocs. In addition, the client wants to provide documentation on
>how to use Web Services instead of a Java object.
>
>I've been a tech writer for a long time, but I'm in new territory
>here. I'm wondering if there is a standard way to approach this (or
>if we are covering new ground).  Can anyone point me to resources to
>get me started.
>
>One thing I'm having trouble with is deciding how much JavaDocs
>information I should include in the Frame reference and how much I
>should simply provide links or references to. If anyone has any ideas
>on how I can started, I would greatly appreciate it.
>
>Thanks,
>Ron

Emily Berk
http://www.armadillosoft.com