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
