From: Gregory Seidman <gsslist+ruby@...>
Date: 2008-03-16T00:15:54+09:00
Subject: Re: How to Read Ruby API / Documentation :NUBY

On Sat, Mar 15, 2008 at 07:00:05AM +0900, Tom wrote:
> On Fri, 14 Mar 2008 12:02:44 -0500, Gregory Seidman wrote...
> >
> >On Sat, Mar 15, 2008 at 01:39:00AM +0900, 7stud -- wrote:
> >> You will have to get used to the fact that the Ruby docs are horrible.
> >
> >The *free* Ruby docs leave something to be desired. The Pickaxe book is
> >pretty good in a lot of ways, and I've also gotten a lot of value out of
> >the O'Reilly Ruby Pocket Reference I won at RubyConf.
> 
> Thanks for the recommendation. Most of the O'Reilly books have been
> helpful to me so I'll check those out first. I've been seeing more
> references to Ruby lately, I figure I might as well roll up my sleeves
> and get started.

Be a little careful there. Notice that I'm recommending a pocket REFERENCE.
I already know Ruby. The best introduction to Ruby for me, coming from
other languages, was Why's (Poignant) Guide (google for it). The Pickaxe
(Programming Ruby <http://www.pragprog.com/titles/ruby> by Dave Thomas et
al.) is also a pretty good introduction. (Yes, the third edition will be
out soon covering Ruby 1.9, but I wouldn't wait for it. It may be worth it
to buy the 3rd edition later as well, but it's worth having the 2nd edition
now.) Just be careful of the difference between introductory/tutorial texts
and references. I can't recommend a specific O'Reilly book for learning the
language, not having looked at any, just the reference for looking up the
things I use rarely and always manage to forget (like whether regexes take
\a or \A and the difference between \z and \Z).

If you already knew all that, consider this a message to others who might
not.

> Tom
--Greg

> >Beyond that, Foo.instance_methods.grep(/bar/) is your friend. Playing
> >around in irb is invaluable. I even look things up in ri occasionally.
> >The wealth of expertise available on this mailing list and on #ruby-lang
> >on freenode.net have also helped me a great deal. And Google is always
> >your friend.
> >
> >Complaining that the free documentation for the free (and Free)
> >language/platform you're using leaves something to be desired is absurd.
> >Feel free to contribute better documentation if you think it's a good
> >use of your time. (Saying it's worth someone else's time but not your
> >own is the height of hypocrisy unless you're willing to pay money for
> >that other person's time.) Otherwise, use the other resources available
> >to you.
> >
> >--Greg