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.
Javadoc is designed to document the API, which it does very well, provided
that the Javadoc comments have been added to the source. If you're doing API
doc, it is extremely useful to be able to write/edit the Javadoc comments in
the source, and I think this role is entirely appropriate for a technical
writer. I work in tandem with the engineers -- they write the first pass as
they're coding, and I go in afterwards and elucidate. You just have to work
out the source control issues. There are tools on the market that make it
easier to add/edit the Javadoc comments, too, although so far I'm not using
them.
I agree with Scott that API doc is improved with additional context and
meaning. One nice feature of Javadoc is the ability to add "see" tags that
point to external doc, whether as a hyperlink or as a hard-coded reference
to a book. I'm using this to point to examples & other usage doc that I
write outside of the source. For example, I have a separate Programmer's
Guide that deals with the product at a higher level, and I can link to that
from the Javadoc source.
However, I find the API doc generated by Javadoc extremely useful on its
own. It shows you how classes and interfaces are related, who implements
what & so forth, all nicely linked in html pages. Your basic hard-core
programmer is going to go right for the Javadoc. The cool thing about
distributing the Javadoc is that a programmer can add it to a project in a
Java IDE and get context-sensitive help on classes and methods. I'd be
leery about _not_ including it (depending on the product, of course),
because it seems like it's become a standard.
- David
>
> Javadoc, provided as part of the JDK package does this. To be sure,
> it is very valuable when you want to document the classes, objects,
> variables, methods, behavoirs, etc. It doesn't write much. It is more
> like a smart concordance generator, or index generator.
>
> You still have to write context and meaning into the docuement.
>
> I am currently doing reverse engineering at my present position to
> create a functional description of our software. Using Javadoc only
> gets me 10% of the way. And the developers quite frankly could and do
> do this on their own. My documentation goes deeper, into the
> functional relationships, who does what to whom, and why.
>
> There is no software that will automatically do that.
>
> Scott
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17) http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by DigiPub Solutions Corp, producers of PDF 2001
Conference East, June 4-5, Baltimore/Washington D.C. area. http://www.pdfconference.com or toll-free 877/278-2131.
---
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.
