From: Josh Cheek Date: 2012-04-24T09:08:22+09:00 Subject: Re: To developers of Ruby: Feeble documentation - weakness of Ruby and the Ruby on Rails (2nd editio --f46d0444721371914a04be618d80 Content-Type: text/plain; charset=ISO-8859-1 On Mon, Apr 23, 2012 at 2:17 PM, Ryan Davis wrote: > > 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. > > As I said "Hmm, don't have the email you're responding to in my inbox -.^" so I can't see the "thorough and self-admittedly subjective critique". This issue has been brought up countless times but looks like it won't ever be addressed. 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: > > Okay, but how frequently do you need to know how something works and find its not documented? For me that's pretty rare. And often the docs would be redundant as the name is sufficiently descriptive. Worst case, you expand the code view. Also, I do think the guides are "really great", they're full of examples, diagrams, notes, they're well structured, and contain both a breadth and depth of information. They omit some of the less relevant parts of Rails, and for those cases, the API usually works for me. It's pretty rare for me to have to go digging through code. Might also be worth noting that I live on Pry, and do a large amount of self-discovery with that. --f46d0444721371914a04be618d80 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On Mon, Apr 23, 2012 at 2:17 PM, Ryan Davis <ryand-ruby@zenspider.com> wrote:

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

> Anyway, I think the OP is wrong, Rails has really great docs:
>
> http://gu= ides.rubyonrails.org/
> http://api.r= ubyonrails.org/

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


As I said "Hmm, don&#= 39;t have the email you're responding to in my inbox -.^" so I can= 't see the "thorough and self-admittedly subjective critiqu= e". This issue has been brought up countless times but looks like it w= on't ever be addressed.

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= :


Okay, but how frequently do you need t= o know how something works and find its not documented? For me that's p= retty rare. And often the docs would be redundant as the name is sufficient= ly descriptive. Worst case, you expand the code view.

Also, I do think the guides are "really great"= ;, they're full of examples, diagrams, notes, they're well structur= ed, and contain both a breadth and depth of information. They omit some of = the less relevant parts of Rails, and for those cases, the API usually work= s for me. It's pretty rare for me to have to go digging through code.

Might also be worth noting that I live on Pry, and do a= large amount of self-discovery with that.
--f46d0444721371914a04be618d80--