Re: Brainstorming ideas how to improve Ruby's documentation

On Fri, Aug 05, 2011 at 06:07:29PM +0900, Adam Prescott wrote:
> I agree with what your overall aim is, which is to improve the non-refere=
nce
> documentation so that new users can learn Ruby more easily. There are
> efforts being made on other discussion threads for that.
>=20
> However, I think as _reference_ documentation, RDoc serves its purpose qu=
ite
> well. It might not be the most cutting edge design, but its more than
> functional enough.
>=20
> I think there would be more problems if we scrapped the reference
> documentation for _just_ tutorial-style material. It doesn't have to be R=
Doc
> 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 introducto=
ry
> tutorial to find the precise definition of String#split(a, b) for example,
> when I already know Ruby.

I think RDoc is mostly fine for what it does, but people tend to misuse
it (or, more precisely, *barely* use it, resulting in *barely* having
documentation).  As a result, a lot of the time the so-called
documentation is basically just an empty space on a page where
documentation should be.  The Web interface with the ugly frames is an
utterly atrocious interface, too; I agree with that.

--=20
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]