From: Josh Cheek <josh.cheek@...>
Date: 2011-08-03T12:03:27+09:00
Subject: Re: Documentation Improvement Proposal

--20cf307d06fe961f5604a9911b19
Content-Type: text/plain; charset=ISO-8859-1

On Tue, Aug 2, 2011 at 7:27 PM, Kevin <darkintent@gmail.com> wrote:

> Right now documentation
> across the board (Not just Ruby's.) in my experience seems to be  a
> list of definitions and not much else.  Imagine trying to learn a
> second language by just reading a dictionary and not being told about
> how to structure nouns, verbs, etc.  Or more accurately imagine
> learning them separately.
>
>
Maybe I'm missing something, but in my mind, that's what documentation is.
Switch it around, imagine trying to learn a second language, and desperately
needing to ask where the bathroom is, but every time you try to find the
translation for "bathroom" you wind up having to wade through three pages of
context / examples.

I think there is merit to what you are suggesting, but I don't think it is
in the docs. Or, if it is, it needs to work with the current style of docs,
because much more frequently I just want to figure out "what was that method
that returns an element from a hash, without invoking #[]" go to the docs
"oh yeah, #fetch". That process should be as streamlined as possible. If you
want to add other stuff as well, that's fine, but make sure not to impede
what I think is the docs' primary function, figuring out what method you
want, what it expects (signature), and what it does (a sentence or two, an
example or two).

I'm generally satisfied with Ruby's docs. There really are only two things I
take issues with. The first is presentation, I prefer the ruby-doc.org style
of presentation. The second is completeness, rdoc.info is much more complete
to the point that I'm probably going to switch. It also has docs for gems,
which I think is really cool. And it filters the list as you search, which
okay. I just find its format harder to follow (possibly because I'm used to
ruby-doc, but IDK, I like that giant pool of methods at the top of ruby-doc
much better than the list at the top of rdoc).

Anyway, that's my two cents.

--20cf307d06fe961f5604a9911b19--