From: Jon <jon.forums@...>
Date: 2011-06-17T23:58:46+09:00
Subject: [ruby-core:37198] Re: ruby core tutorials location

> > My feedback was specific to the suggestion of embedding links into the Ruby source tree, not the issue of whether more documentation is needed. For the tutorials scenario you raised, I believe links from http://www.ruby-lang.org/en/documentation/ (e.g. - a new Tutorials section) are a more adaptable and maintainable _implementation_ for dealing with documentation realities than links in source.
> 
> How about links in the source code back to the tutorials section in
> question? (e.g. a link to the user editable tutorials section for that
> class, etc.)?


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

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.

Yeh, I'm singing the High Maintenance blues song again, but...

But you've also got me thinking of another option...or maybe it's the coffee.

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.

It's *one* link in the source that isn't a PITA to manage. It's a link that's a pointer-to-a-pointer-like indirection which minimizes the number of times it needs to be updated.  You isolate maintenance to just those people managing ruby-lang.org rather than potentially every ruby-core dev.

I don't know who owns the documentation section, but JEG2 has helped me in the past to place RubyInstaller info on the downloads page.

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