From: Chris Kottom <chris@...>
Date: 2011-08-05T18:56:16+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

--000e0cd30368a02c7404a9bf1b12
Content-Type: text/plain; charset=UTF-8

I think you can't really rag on RDoc for not producing tutorials.  That
would be like me getting mad at my fridge over the quality of the toast it
produced - wrong tool for the job.

As for the format, there are certainly improvements to be made.  RDoc is on
GitHub too, and the project already has a templating system built into it.
 (BTW, I just checked, and sendmeapullrequestforthat.com is still available
in case anyone wants it.)

On Fri, Aug 5, 2011 at 11:52 AM, Chad Perrin <code@apotheon.net> wrote:

> On Fri, Aug 05, 2011 at 05:48:08PM +0900, Marc Heiler wrote:
> >
> > Let's consider a new user again. He visits at:
> >
> >   http://www.ruby-lang.org/en/
>
> [snip]
>
> >
> > Please, I love ruby and matz is a genius, but contrast this to:
> >
> >   http://docs.python.org/tutorial/index.html
> >
> > That's right. The Python homepage tries to TEACH people HOW TO USE
> > PYTHON.
>
> Did you notice that on that ruby-lang.org link you provided there's a
> menu item to the right that says "Ruby in Twenty Minutes"?  It leads to a
> quick introductory tutorial for basic Ruby use.  I'm not sure your
> comparison with Python is entirely fair, considering you're comparing an
> apple (Ruby API docs) with an orange (a Python beginner tutorial).
>
>
> >
> > Please, kill rdoc at once even if no alternative exists. No alternative
> > is still better than the crap that is called Rdoc.
>
> From what you've said so far, I don't think your problem is with RDoc per
> se; I think it's with the atrocious frameset Web interface.
>
> --
> Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]
>

--000e0cd30368a02c7404a9bf1b12--