From: Ryan Davis <ryand-ruby@...>
Date: 2012-04-24T04:17:41+09:00
Subject: Re: To developers of Ruby: Feeble documentation - weakness of Ruby and the Ruby on Rails (2nd editio


On Apr 23, 2012, at 06:07 , Josh Cheek wrote:

> Anyway, I think the OP is wrong, Rails has really great docs:
> 
> http://guides.rubyonrails.org/
> http://api.rubyonrails.org/

I can't believe the attitude I'm seeing in this thread. Someone writes a very thorough and self-admittedly subjective critique of our beloved ruby (and rails) and all he gets is people jumping down his throat saying he's wrong or confused. He's not. He's totally right.

Really great? I couldn't disagree more. I completely agree with the OP that both ruby and rails have a long way to go before our documentation is "really great". For example, `rdoc -C lib` inside of activerecord:

> Files:       144
> 
> Classes:      82 ( 28 undocumented)
> Modules:      90 ( 63 undocumented)
> Constants:    21 ( 20 undocumented)
> Attributes:   91 ( 84 undocumented)
> Methods:     822 (385 undocumented)
> 
> Total:      1106 (580 undocumented)
>  47.56% documented

That's the oldest and most established subproject in rails... meaning, it has the least excuse to be less than 50% documented.

Ruby has the same problem, but at least Eric Hodel and others are (semi-)actively doing something about it. It still has a long way to go before it is "really great":

> Files:        764
> 
> Classes:     1293 ( 620 undocumented)
> Modules:      302 ( 146 undocumented)
> Constants:   2195 ( 828 undocumented)
> Attributes:  1013 ( 438 undocumented)
> Methods:     9440 (2459 undocumented) ONE IN FOUR!
> 
> Total:      14243 (4491 undocumented)
>  68.47% documented

The numbers speak for themselves, as do the really basic questions on this mailing-list, ruby-forum, stackexchange, etc.

And before anyone starts up on the "great" commercial documentation available... do we really want to have a paywall as our barrier to entry?