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.
June 25, 2007 at 9:15 pm
Great project and article!
I think the biggest area for improvement in Ruby documentation is the ability for users to discuss and add additional examples. Normally I don't have anything too nice to say about PHP, but the php.net docs with user comments can be really helpful... some of the stuff users submit is aweful, but often the comments address holes in the docs.
From time to time as new PHP versions are released, the official docs are updated to make the user comments obsolete. And over time there has been tremendous steady improvement to the docs.
It would be great to have this kind of thing built right into rdoc, where user comments get posted to pastie or to a wiki somewhere so that they can be viewed inline with the rdoc and also coalesced into future documentation.