From: Shadowfirebird Date: 2008-08-05T23:43:39+09:00 Subject: Re: perl and the culture of libraries 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. To forestall criticism of my comment: 1) Yes, I'm aware that there are any number of excellent books to buy, but a FOSS language needs good FOSS documentation. 2) Yes, I'm aware of the pickaxe, obviously. It's a first-class (pun intended) introduction to the language. And the poignant guide. But apart from that, where are the websites with tutorials in the medium-to-advanced level? Where's the wiki that takes you through all the gotchas and special features of Ruby?* Other languages have them. 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. 4) Yes, I'm aware I'm feeling very cranky today. Sorry. I'm really not trying to pick holes in Ruby. I'm just saying that if you want to document a gem, you need to write a coherent guide explaining what it does and pointing out the more common options, with a couple of tutorials. Writing documentation isn't easy, of course, and worse, it takes different skills to writing code. But, it's not something that can be skipped. Shadowfirebird. * Okay, we know where that last one is: under 10 feet of spam. Still. On Tue, Aug 5, 2008 at 3:14 PM, Martin DeMello wrote: > On Tue, Aug 5, 2008 at 7:05 AM, Peter Fitzgibbons > wrote: >> Isn't it true, though, that rubygems are the defacto distribution model for >> projects in RubyForge ? >> If so, then, like packaging a CPAN .tgz that includes the ./t, ./doc, ./lib >> and Makefile.pl, >> the "default" gem hierarchy created/expected by the gem tools should also >> have ./test, ./doc, and ./lib directories > > Yeah, but *expecting* it is a pretty disruptive change. it's hard to > do it incrementally. having hoe create a structure like that wouldn't > be a bad idea, though. > >> Also, I seem to recall that although many (most?) projects on CPAN include >> the usual-suspect titles in the documentation >> (Name, Synopsis, Description...), those titles really are purely cultural, >> there is nothing in POD spec that declares what the >> title should be... just "convention" > > However, since Perl has settled on said usual-suspect titles, we might > as well take advantage of their experience and adopt them wholesale :) > Again, it wouldn't be something that, say, the gemspec enforces - all > I want to do is provide a tool to make adding those sections the path > of least resistance. > >> A lot of this has to do with the 25yrs of history w/ Perl vs the 12yrs >> history w/ Ruby. 12 years is a long time... but seems to me >> a short time in social-cultural development. > > Very true. Nothing says we can't stand on the shoulders of the perl > giants, though :) > > 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