From: "M. Edward (Ed) Borasky" <znmeb@...>
Date: 2007-11-28T00:14:30+09:00
Subject: Re: So, here's a challenge!

Jari Williamsson wrote:
> Why are there so few projects on Rubyforge that leave their alpha/beta 
> stages to Production/Stable? Why are there so few libs with really good 
> documentation? Why is there not even good documentation on how to create 
> a Gem or maintaining it with Hoe? Why are there so few documentation 
> packages that use anything other than the old frame-based default 
> template? And so on.

Well ... there are a finite number of developers but a potentially 
infinite number of good ideas for projects. Given that, projects tend to 
self-organize around "leaders" and tend towards a distribution where 
there are a few large successful projects like Rails, RSpec and Ruby 
itself, and a few small successful projects like the One-Click 
Installer, RubyGems, Rake, Hoe, ZenTest and Heckle. The rest of the 
infinite number of good ideas are one-person projects that probably 
don't go anywhere.

> Anyway:
> Is there a utility that analyzes the data that RDoc is processing for 
> documentation (or analyze the result)? It should scan for methods with 
> missing documentation, methods with missing examples, count 
> cross-references, etc, etc. If not, this is the challenge: to create 
> such a utility!
> Developers should get help to spot weak documentation and it should be 
> possible to rate one's documentation and be able to say things like 
> "Documentation gets a 97% quality rating by <name of utility>".

There are tools like that for many languages. I think the technical term 
is "document coverage". There is also literate programming. Again, it 
depends on whether you want to do one thing really really well and hope 
it catches on, like Rails did, or do lots of things and when one *does* 
catch on, let it self-organize into a sub-community. And if it *never* 
catches on, well, welcome to the 95 percent of the "mud that didn't get 
to sit up and look around." :)