Can anyone share with me how you write Javadoc?

Question

Can anyone share with me how their companies write Javadoc?
Are your developers solely responsible for it? Do your technical writers own it or review it? How do you make sure it's good?
Right now, my software developers are mostly responsible for writing all the API info and it's of poor quality and really lacking details. I don't mean spelling/grammar-type problems. My developers just don't seem to "get" what information to include, no matter how many guidelines or checklists I give them.
A very simple example is:
* Gets the status
public java.lang.Integer getStatus() {...}With no indication of what status values may be returned and what the values might mean.
How do you ensure that what you write is actually useful? Please help!
I'm aware of the method Sun recommends, but I want to know what others do.
Thank you

Answer 1

Hi,
Well, concerning the question what a good API documentation should be. Just imagine, you are a programmer and you want to use that API. You need to know how it works. There can be only three ways to find it:
(1) The API documentation
(2) Probing experiments. Even a good documentation may not describe everything. Sometimes, the only way to understand certain things you particularly need may be guessing something, writing a code basing on it and see how it works. Then, guessing something again, more precisely now, and so on. Even a very good documented API (for instance, javax.swing) may require that sort of approach to be able to use it eventually.
(3) At last, when source codes are available, one may look at them and try to understand precisely, what a particular method actually does.
I think the better the API documentation the less one may need to endeavor those two last steps. There is actually a limit about it. Without any proper explanation at all, one may never be able to use a particular API, neither after probing it nor after looking at source codes (that is not to say the sources may be simple unavailable at all).
Concerning how to write the API documentation, that's mostly the question of managing your team. I think, basically, the original source of the ultimate information about everything implemented in the projects are those very programmers (developers) and, probably, some software architects. But those guys normally are not especially eager to write any documentation (especially developers). That your example just demonstrates it. It seems, your programmers just wrote that "Gets the status" for you to make them leave in rest after that. In addition, the programmers normally have such a sort of work and activity that does not match particularly well with the writing literature and doing their main job simultaneously. You should not enforce them to do that!
To write a good documentation, you will need to engage a technical writer. That's normally a guy with some programming background. However, writing some literature is actually what he does the best. (Sometimes, such people do something else about written word beyond the technical writing.) The job of that guy would be to write the documentation. This will take from him (or her) two basic things:
(1) The ability to understand the whole software system (that's where his programming background will be needed!);
(2) To communicate with the programmers who have developed the stuff and to obtain from them all the necessary information they know. That may require some personal (verbal) communication with them, because asking them to write everything again will only result in the same "Gets the status" explanations. However, to be successful in this, the technical writer needs to have some explicit management approval behind him. Otherwise, some of the guys will avoid speaking to him at all (saying they lack the time). So, the management should assign them the necessary priority for such communications.
Particularly big projects may even need to have the whole team of technical writers.
Anyway, writing docs is a hard work. But it is extremely important! The good documentation may both increase your sales and eliminate lots of expense on further support of your customers.
Regards,
Leonid Rudy
http://www.docflex.com