> > Rather than adding links to source code, I would prefer the wikibooks link and others under a new Tutorials section of http://www.ruby-lang.org/en/documentation/ as well as adding http://ruby.runpaint.org/ to the existing Getting Started section.
> 
> Yeah, adding links there is good, but what I'm trying to create here
> is more easy connection between the core rdocs and (any existing)
> tutorials...just having a link to the various books isn't a strong
> enough link (from my perspective, anyway).
> 
> Another option might be to link from the core rdocs to some tutorial
> "index", which could provide a list to the various tutorials/online
> books' subsections, I suppose.

I like what you're trying to do and see how great that tutorial connection from rdoc/yard could be, say, mixing with existing ruby-doc.org and rubydoc.info.  But I question embedding source links to info in which the info can easily grow outdated or abandoned as time passes. I also question the ongoing maintenance burdens.

It's one thing to update a few links on a web site, but another to have to mod a large number of links in source across multiple repo versions when docs at those links become abandoned. While your "blessed"/"index" idea notably attempts to address this (and minimize the documentation burden on core developers) I still prefer the "pointer like" indirection of links from a "well known" website.

I prefer concise usage/example comments in source and counting on the elaboration to grow, morph, and adapt organically in the community.  Google, word-o-mouth, twitter, blogs, youtube, books, vimeo, etc helps minimize the search costs as does a maintained/culled Documentation section on ruby-lang.org.

And think of the number of times you've found amazing things when fishing outside of the "approved mainstream" documentation sources :)

Jon

---
blog: http://jonforums.github.com/
twitter: @jonforums

"Anyone who can only think of one way to spell a word obviously lacks imagination." - Mark Twain