Re: Has anyone used JavaDoc?

Subject: Re: Has anyone used JavaDoc?
From: "Susan W. Gallagher" <susan-gallagher -at- vertel -dot- com>
To: mmoore100 -at- hotmail -dot- com, "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 05 Jun 2000 15:05:03 -0700

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




Previous by Author: RE: Study on how people read online news
Next by Author: Re: UML resources?
Previous by Thread: Documentation Plan
Next by Thread: RE: Has anyone used JavaDoc?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads