From: Roger Pack Date: 2011-06-22T11:34:18+09:00 Subject: [ruby-core:37284] Re: ruby core tutorials location > In addition to the work to correctly add/sync the links in code to the right section, just a couple of the unintended consequences scenarios I'm concernced that would increase source code churn and maintenance: > > 1) Competition for "placement" in the Ruby source - there will likely be multiple people wanting *their* links embedded in the source which could lead to an unnecessary pestering of the core devs by those wanting to sell their doco as The Best Ruby Tutorial for All Time. �Hey look, it's *my* doco that's the *official* tutorial in *the* Ruby source. �I know, I know...over-the-top and a boring conspiracy theory ;) I think that competition for ruby documentation would be an excellent problem to have :) (my guess is that some "gentleman's agreement" could be reached like most recent on top, etc.) What I'd like to have ideally is one official "blessed" tutorial (user editable, of course), then below that links to the various out there. Reasoably low maintenance. > 2) Stale tutorials cause unnecessary ruby-core issues/questions - if *any* of the tutorials are out-of-date, since the links are in the source, people are likely to feel motivated to help correct the error by creating more bug reports on redmine. This style of report is different than an outdated rdoc report and I suspect would be viewed as unhelpful noise on redmine. I suppose errata to tutorials could be added to their listing on the index page, but most tutorials allow for comments, and, since they'd be on "non blessed" sites I think people would tend to just leave comments on the tutorial itself... > How about requesting core to add a *single* link to https://github.com/ruby/ruby/blob/trunk/README (and .ja) that points back to a new Tutorials section of http://www.ruby-lang.org/en/documentation One of the links in this new section points to the wikibooks site you mentioned. There is already a link to the wikibook on ruby-lang.org/en/documentation, and that doesn't seem to have been enough, since it already does have several tutorials, but nobody "navigates through" to them because it's too indirect, so doesn't quite fit what I'm describing. I'd be quite happy to have a wiki page on https://github.com/ruby/ruby become "blessed" though, that has potential (again rdoc links back would be invaluable). Cheers, -roger-