Thoughts on Documentation: Quality

Recently I've been working on my Google Summer of Code project dcov (a Ruby documentation analyzer) a lot. It's basically broken into two large functions: analyzing your documentation and reporting on it. I don't have to do much on reporting (thanks Ruport!), but on the analysis side I'm basically making it up as I go. The first part of the analysis is quantity: is something documented? Right now, this works famously: it can give you a precise precentage of your functional unit documentation coverage. This is easy, of course, because all it has to do is check for the presence of a comment. The second part is quality, and that's where the analysis gets a little hairy.

There are no documentation standards for Ruby/Rails really (I'm working on an entry on this...so bare with me), and so I'm sort of left to my own devices when analyzing quality. The plan is to allow users to write their own analyzers and thus let them create their own quality standards, but it would be nice to include a "default" quality analyzer. The problem though is not what it should do, but how?

Quality is so subjective, that if we're to do a midline, objective analysis, a standard needs to be developed or some sort of criteria needs to be met. This entry is little more than a plea to you guys and gals: help me create one! What do you think makes good quality API documentation? I'll reconcile your responses into something workable in a future entry and that will become dcov's standard criteria set (until we decide to change it ;)). Here are a few of my ideas:

• Parameters should at least be mentioned.


• Options hash must be documented if present.


• Default values must be explained.


• A return value description should also be present, if there is a return value and it is not apparent.


• Examples! Examples! Examples!

Let me know what you'd like to see.