From: Jon <jon.forums@...>
Date: 2011-06-14T22:43:35+09:00
Subject: [ruby-core:37137] Re: ruby core tutorials location

> > 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.
> 
> What makes you think that info in a wiki will grow outdated or be
> worse than the current rdoc?  (The fact that it's a wiki is meant to
> help the maintenance burden be less in this regard--self-grooming).
> The standard view of ruby is that basically you have to "buy a book"
> in order to get quality documentation for it.  This is meant as a
> first step to higher quality documentation.
> 
> I am aware of the links to various ruby documentation on ruby-lang.org
> and ruby-doc.org (and indeed there is some quality work out there--the
> original pickaxe being one), however, coming from a long-time Ruby
> user, this doesn't seem to quite cut it.   (ex: runpaint.org -- search
> for "Socket" examples--there are none.  Where are the tutorials in the
> core rdoc's for "udp broadcast" -- there are none.  They don't even
> seem to belong in core rdocs, but would be useful in some tutorials
> section.).  Ruby could well benefit from a "blessed" section of
> tutorials, at least from my perspective.  I don't understand why we
> wouldn't want *more* tutorials rather than less.

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.

One person's perspective. Don't let it deter you from continuing to enhance Ruby's documentation. I think what you're doing is valuable and I appreciate the time and effort you're putting into it.

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