For many Java facilities, including most open-source packages and most internally developed components, the reality is that very few class libraries or components come with any significant documentation besides the Javadoc. This means that developers will be learning to use facilities from the Javadoc, and we should consider organizing our Javadoc around this reality. I’ve often joked that one of the most important skills for a Java programmer today is the skillful use of Google and Javadoc to reverse-engineer poorly documented APIs. It may be true, but it’s not really very funny.

Read the rest in this develperWorks article. via codaland.