From: Martin DeMello <martindemello@...>
Date: 2008-08-05T23:54:50+09:00
Subject: Re: perl and the culture of libraries

On Tue, Aug 5, 2008 at 7:43 AM, Shadowfirebird <shadowfirebird@gmail.com> wrote:
> I don't wish to be critical (I really don't!  That's not just a way of
> opening a sentence!) but in my experience there's very little
> documentation in Ruby at all.  And I'm not convinced that having a
> little form with each gem giving the name of the author and a brief
> description of what it does is going to help that much. Authors that
> want to include that are already finding ways of including it in the
> rdoc, usually in some sort of 'readme' entry.

[...]

> 3) Yes, I'm aware of rdoc.  But I'm sorry, that's not really
> documentation.  It's just a way of reading the comments without having
> to wade through the code.  For some people, it's all that is needed.
> But for others it's just confusing.

You can't have it both ways :) And this is indeed the specific problem
I would like to address - rdoc is too tied into the code, and a readme
file isn't structured enough to get past the blank canvas effect -
it's a mental effort to decide what to put into it.

martin