[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

Re: Javadoc resources for tech writers?

Subject: Re: Javadoc resources for tech writers?
From: lyndsey -dot- amott -at- docsymmetry -dot- com
To: Isaac Rabinovitch <isaacr -at- mailsnare -dot- net>
Date: Thu, 05 Feb 2004 21:36:00 -0500

Isaac Rabinovitch writes:

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: http://picknit.com/isaac.htm.
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.
I seem to be missing something here. Several years ago I was tasked with writing a programmer's guide, and someone suggested that I use Javadoc. I got access to the code files, ran them through Javadoc to get the HTML output, which, if I remember correctly, contained a subset of what I described in my reply to Joyce. Because the output was missing some important info, I decided that it was not useful enough and so I printed the source code and created the programmer's guide from that.
It seemed to me that Joyce was asking about writing something similar and she needed the information generated by the Javadoc, but did not understand the output well enough to feel confident writing about it. You and others seem to have interpreted her query quite differently, but I don't understand your interpretation. On the assumption that other list members might be confused too, perhaps you could elucidate.
Thanks,
~~~~~~~~~~~~~~~~~~~~~
Lyndsey Amott
www.docsymmetry.com
Winnipeg, MB R3G 2J3



References:
Re: Javadoc resources for tech writers?: From: Isaac Rabinovitch

Previous by Author: Re: Javadoc resources for tech writers?
Next by Author: Re: Really Annoying Help (WAS Saying "RTFM" out loud (was Everyday [was: Style question: "war d ial" ...
Previous by Thread: Re: Javadoc resources for tech writers?
Next by Thread: Re: Javadoc resources for tech writers?

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

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

Sponsored Ads