From: Peter Fitzgibbons Date: 2008-08-06T00:38:43+09:00 Subject: Re: perl and the culture of libraries ------=_Part_21791_7030881.1217950814509 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline OTOH, _why is a performance artist, poet, and genius. A very high bar for us nerdy anti-social shmoes who usually have trouble coming up with something more creative than "Happy Birthday". Peter Fitzgibbons (847) 687-7646 Email: peter.fitzgibbons@gmail.com IM GTalk: peter.fitzgibbons IM Yahoo: pjfitzgibbons IM MSN: pjfitzgibbons@hotmail.com IM AOL: peter.fitzgibbons@gmail.com On Tue, Aug 5, 2008 at 10:24 AM, Shadowfirebird wrote: > _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 > wrote: > > On Tue, Aug 5, 2008 at 7:43 AM, Shadowfirebird > 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 > > ------=_Part_21791_7030881.1217950814509--