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