New Approach to Documentation

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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s