TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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!