From: Adam Prescott <adam@...>
Date: 2011-08-05T18:07:29+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

--90e6ba6e8d44626bae04a9be53d7
Content-Type: text/plain; charset=UTF-8

I agree with what your overall aim is, which is to improve the non-reference
documentation so that new users can learn Ruby more easily. There are
efforts being made on other discussion threads for that.

However, I think as _reference_ documentation, RDoc serves its purpose quite
well. It might not be the most cutting edge design, but its more than
functional enough.

I think there would be more problems if we scrapped the reference
documentation for _just_ tutorial-style material. It doesn't have to be RDoc
which produces the reference docs, of course, but we do need to keep both
levels of information. I don't want to have to walk through an introductory
tutorial to find the precise definition of String#split(a, b) for example,
when I already know Ruby.

--90e6ba6e8d44626bae04a9be53d7--