Re: Javadoc resources for tech writers?

Subject: Re: Javadoc resources for tech writers?
From: Isaac Rabinovitch <isaacr -at- mailsnare -dot- net>
To: techwr-l
Date: Thu, 05 Feb 2004 16:58:48 -0800

Joyce Fetterman wrote:

I have searched the Sun Web site and I've found the answers to many
questions, but I'm hoping for a resource that looks at Javadoc from a TW's
perspective. I have read "How to Write Comments for the Javadoc Tool", but
that assumes an understanding of Java.

Yup, and you're not going to get around that. The whole point of JavaDoc is for programmers to maintain their own documentation. It's used by writers too, but the writers *must* be comfortable editing Java source code. If that's beyond your ability, then you just shouldn't mess with the files at all. You run the risk of breaking, not just the documentation, but the build for the library you're trying to document.

I see two workarounds. One is to use JavaDoc to generate HTML and edit *that*. Not a good production method, of course,

The other is to hire a writer who knows Java well enough to be trusted with the source files. Which is my cue for linking my resume:

Tools like JavaDoc and DOxygen have a lot of promise, but their designers have woefully neglected the workflow problems you get when programmer and writer have to work out of the same file. I guess I shouldn't complain: I'm up for two contract jobs based largely on my JavaDoc/DOxygen expertise -- and on the fact that I can be trusted to edit a source code file without breaking a build.


Previous by Author: Re: Documentation and Bug Reports
Next by Author: Re: Where does Documentation belong?
Previous by Thread: Re: Javadoc resources for tech writers?
Next by Thread: Re: Javadoc resources for tech writers?

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

Sponsored Ads