_Why does a good job of this sort of thing, when he nails the syntax
of, say Hpricot or sqlite in a couple of pages.  Really I think that
is the sort of thing that we should be aiming towards.

http://whytheluckystiff.net/articles/aQuickGuideToSQLite.html

On Tue, Aug 5, 2008 at 3:54 PM, Martin DeMello <martindemello / gmail.com> wrote:
> 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
>
>



-- 
All you can do is try to know who your friends are as you head off to
the war / Pick a star on the dark horizon and follow the light