Documentation usually has these three attributes: It’s incomplete, outdated and plain wrong.
That doesn’t apply to every bit of information in your documentation but it you can be sure the statement above is correct for the whole documentation.
As a consumer of such documents, it’s a nice puzzler to determine into which of the three categories a bit of information belongs.
This leads to the common “we hate documentation” stance that all software developers soon adopt, no matter if they have to write/maintain the documentation or if they have to use it.
As we all know, the only reliable source of documentation are unit tests. But they can still be incomplete (= missing the example you need) or outdated (= missing examples for the latest API).
The solution? Generate documentation from the source code. And I don’t mean “from javadoc in the source code”, I mean literally from the code. If a method is used in a certain way in 317 places in your code and once in a different way, then you have two examples. One of them probably works, the other is probably documents a bug which your tests missed.
Eclipse is starting to get support for this. The first step was code completion. Now we have a couple of guys working on Eclipse Code Recommenders.
This summer, Stefan Henß starts to work on an “extended documentation platform” for Eclipse.
Dark Views 