I haven't been on news.YC very long, so maybe that was mentioned as an issue a while ago. When Rails first came out, there was a paucity of documentation. The book "Agile Web Development" came out to meet the need. Now when I go into a bookstore or search through Amazon, I'm shocked by the number of books on Rails and Ruby. Truly amazing. Then there are the self-published outlets like peepcode.com, flexiblerails.com, etc. Rails and Ruby coders are also active bloggers and IRCers. The folks at Caboo.se, in particular, have been working on internals documentation. (http://www.caboo.se/documentation)

In the rails API docs (api.rubyonrails.org) next to each function you can click 'show source' to see what's going on under the hood. I hardly have to do this.

But when I do, it's usually just 5-20 lines of code that's not that complex to grok. (but you're right, not many comments inline) It would not be fun to try and decipher RoR internals as a new ruby programmer.

There's also the caboose edge API documentation. It's updated 3x per day from the most recent rails edge code and has all the private (#:nodoc) methods exposed:

http://caboo.se/doc.html

If you think rails internals needs more documentation and can help, check out the Rails Documentation project:

http://www.railsdocumentation.org/