Can anyone share with me how you write Javadoc?

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

leonid_rudya at 2007-7-13 19:40:09 >