How would you define “quality” Ruby documentation?
This is a call for help and opinions! One of our finest needs your input..
Jeremy McAnally (a.k.a. Mr. Neighborly), author of the fine Mr. Neighborly's Humble Little Ruby Book, is busy working on his Google Summer Of Code project, dcov, a Ruby documentation analyzer. Some aspects of developing dcov are easy (such as reporting or basic coverage analysis), but Jeremy's having problems when trying to work out how to analyze the quality of documentation.. so he's looking for input:
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 bear 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?
Head over to his plea for help for more info, or leave comments here at Ruby Inside.. he'll be reading. If Jeremy finishes dcov, it could become an essential tool for analyzing and improving documentation standards in the Ruby community (something I have seen complaints about from Ruby newcomers), and it might be your ideas that help it happen.