From: Chad Perrin <code@...>
Date: 2011-08-05T18:46:29+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

--ibTvN161/egqYuK8
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

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 ]

--ibTvN161/egqYuK8
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (FreeBSD)

iEYEARECAAYFAk47t+EACgkQ9mn/Pj01uKUPpwCfaDMXbagui+UnOOLqFShjP9nF
wp8AnRkGpG6sxuG7O9CEhBKy9WXmqv4y
=ZiwV
-----END PGP SIGNATURE-----

--ibTvN161/egqYuK8--