We have Javadoc, which is an excellent tool. Class comments are the perfect place to explain what each class does, how it works, what it interacts with, etc. The problem is more the mentality than the tools, unfortunately. "We don't need to document this, we're the only ones who will ever see it"
At my last job, one of my tasks as the company's only technical writer was to clean up and make comprehensible the stuff that the developers had typed into the Javadoc. This was because although they had often entered information, since they were required to do so, it was almost invariably in one of three states (or sometimes a combination):
Original material, verbose, mispelt, incoherent, and requiring major editing.
Original material, written in very generalised form so that it can be recycled for (3)
Material cut-and-pasted from (2) - and, occasionally, from (1) - to fulfil the requirement of having something in the Javadoc.
![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png)
branchandroot
Re: but...
Date: 2003-01-24 13:27 (UTC)At my last job, one of my tasks as the company's only technical writer was to clean up and make comprehensible the stuff that the developers had typed into the Javadoc. This was because although they had often entered information, since they were required to do so, it was almost invariably in one of three states (or sometimes a combination):
Original material, verbose, mispelt, incoherent, and requiring major editing.
Original material, written in very generalised form so that it can be recycled for (3)
Material cut-and-pasted from (2) - and, occasionally, from (1) - to fulfil the requirement of having something in the Javadoc.
Listed in order of preference...