From: Eric Hodel <drbrain@...7.net>
Date: 2011-08-09T03:21:29+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

On Aug 6, 2011, at 1:28 PM, Chad Perrin wrote:
> On Sun, Aug 07, 2011 at 04:39:16AM +0900, Eric Hodel wrote:
>> On Aug 5, 2011, at 7:05 PM, Chad Perrin wrote:
>>> There's a crapton of stuff in perldoc that doesn't have an equivalent in
>>> ri, though.
>> 
>> Ruby 1.9.3 is over 65% documented while Ruby 1.9.2 was under 55%
>> documented.  This increase was due to contributions from the community
>> after my documentation challenge.  If there's stuff you'd like
>> documented please contribute:
>> 
>> http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge
> 
> When I say there's a crapton of stuff in perldoc that doesn't have an
> equivalent, I'm not talking about the percentage of the language's API
> that has basic argument, return value, data type and minimal syntax
> documentation.  I'm talking about the explanatory text that comes in many
> of the special perldoc pages.  It gives a deeper understanding of the way
> things work in the language through lucid, extensive descriptions of how
> things work, in a way that does not exist in the Ruby world as far as
> I've seen apart from short articles and tutorials scattered around the
> Web and a number of excellent books.

For Ruby 1.9.3 I wrote explanatory text for OpenSSL and a second contributor and I worked together to provide better explanatory text for Net::HTTP.  There were a couple patches I applied to add better explanatory text to various parts of the standard library.

> . . . and that, really, is Ruby's documentation strength: the community
> is overflowing with authors who have written and published really
> excellent books (though ri is nice for what it is, too).

If we're missing it then provide a patch, even if that means contacting an author and asking to make a contribution based on their work.