Re: Has anyone used JavaDoc?

["Susan W. Gallagher" <susan-gallagher -at- vertel -dot- com>]

At 12:03 PM 6/5/00 +0000, mmoore100 -at- hotmail -dot- com wrote:
>I'm doing a large project which includes a number of Java APIs... 
>JavaDoc ... basically ...just reads the developer's comments 
>in the source code an outputs it as HTML. One still needs to write an 
>overview and show samples and so on.
>
>...We use FrameMaker to produce 
>printable manuals. What I'd like to do is use create FrameMaker pages with 
>overview and examples and paste in the output from JavaDoc, but maybe 
>that's not the correct approach. Any ideas?

First, you're treading on dangerous ground if you're thinking of taking
the javadoc output away from a Java developer. Whatever you decide to
deliver, make it a point to include the html files as well. Java developers
have come to expect and rely on the javadoc output.

Secondly, javadoc output in its current form is so full of frames and
tables you'll develop a marked propensity for lip-diddling and may even
start to drool if you try to convert it to linear output for paper delivery.
;-)

I suggest developing a user-guide type document to accompany the javadoc
output. Create your overview, use your examples to discuss the product
features, and point users to the html reference for more information.
If you can deliver an online document that hyperlinks to the javadoc
reference, so much the better.

That does not mean that you should have no influence over the javadoc
output. Whether your development team gives you editorial access to the
source code or not, you need to influence the output to maintain the
level of quality your customers are used to. Don't be shy on this point;
It's already been the start of many a turf war!


-Sue Gallagher               http://pw1.netcom.com/~gscale/susanwg/
susan-gallagher -at- vertel -dot- com   http://www.vertel.com

The _Guide_ is definitive.
Reality is frequently inaccurate.  --Douglas Adams