Re: How JavaDoc works with other docs
I'm a Frame/Webworks guy dealing with JavaDoc for the first time. My
question to you has less to do with tools and more to do with how JavaDoc
and supplemental documentation co-exist.
I am producing a programmer's guide for one of our products. The main
programmer has provided JavaDoc files in html. I have written two chapters
that add information not included in the JavaDoc.
But how do these things go together???
Andrew,
First analyze the type of additional information you're
providing.
JavaDoc gives you pure reference info; is what you're
providing supplemental reference material, conceptual
material, or procedural material? What you've written
can affect where you put it.
If you've got conceptual and procedural material to
add, then publishing a separate document ain't no
big. User manuals and reference manuals have lived
side-by-side for a long time. Providing hyperlinks
between the two shouldn't be much of a problem,
either.
If you have supplemental reference material, then
you should integrate it with the JavaDoc output,
and you've got lots of options.
First, add it to the source code. JavaDoc is just
a tag language that's embedded in the source file.
If you can learn HTML (or, for that matter, coal-
burning WordStar! <g>), you can learn JavaDoc.
All the documentation is freely available on Sun's
Java site. Email your tags to the programmer with
instructions as to where they should go and then
relinquish ownership of them.
Alternatively, learn the tags and arrange with
the programming staff to edit the JavaDoc
comments directly. This approach requires that
you've already earned the respect and trust of
the developers 'cause ain't no way they're gonna
allow you to muck about in the code otherwise.
That said, it is your responsibility as a tech
writer to edit the reference material anyway and
none of the programmers are going to take the
time to re-arrange the commas to your liking
and make each method description begin with an
active verb -- even if you manage to make them
understand what an active verb is! ;-)
And as a last and least desirable alternative,
generate HTML from Frame and patch the two HTML
documents together before the final release of
the software. Just recognize that if you take
this approach, you must merge the documents each
time that new JavaDoc output is generated.
HTH!
-Sue Gallagher
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
Free copy of ARTS PDF Tools when you register for the PDF
Conference by May 15. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
References:
How JavaDoc works with other docs: From: Andrew Dugas
Previous by Author:
RE: What Are the Main Problems You Have with MS Word?
Next by Author:
Re: Style to Style on a Friday afternoon.
Previous by Thread:
How JavaDoc works with other docs
Next by Thread:
RE: How JavaDoc works with other docs
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads