Php's docs are good, really good.  But I always felt that it's because
it's a domain specific language.

It lives, breaths and is a web language.  Sure, you can use it as
general purpose, but it was designed for the web.
With that mindset they made possibly the best web-friendly docs I've ever seen.

Ruby on the other hand was developed because some hacker got an itch,
and wanted something kindof like lisp, only better.
It's definitely documented like a hacker language.  Good docs are
eventually written, but very rarely updated, because hackers generally
have something better to do than document: hack their language and
make it better.

There needs to be something like a ruby-illumination (see
http://en.wikipedia.org/wiki/Illumination_(manuscript) ) going on.
Maybe at the big ruby conferences a bunch of ruby hackers can be paid
in pizza to spend 8 or so hours on a mass documenting session.  Make
the docs beautiful in every way: correct, complete, elegantly written,
indexed, and, of course, aesthetically.
For fun have them all in monks robes, and bring them dark German
beer.....but no more than 1L per hour.

Just my thought.
--Kyle