From: Thomas Volkmar Worm <tvw@...4r.de>
Date: 2008-08-06T20:38:33+09:00
Subject: Re: perl and the culture of libraries

Hi,

Shadowfirebird wrote:

> 2) I'm not convinced that CPAN does documentation any better than
> rubyforge/gem does.  This isn't a matter of having standard fields or of
> rewriting our packaging system.  We actually have to get our hands dirty
> and write in ... you know ... English.> 

You are somewhat right. Of course no or little documentation is a general 
problem at all, not a ruby or rubyforge/gem specific one. But the main 
difference is, how CPAN encourages the developer to provide a 
documentation too: The documentation is the first thing you see and 
searching on CPAN is searching the documentation. And by reading the 
documentation top-down you very quickly (often after a couple of lines) 
find out, what the lib/package is about.

Every developer on CPAN uses CPAN himself and sees the benefits it brings 
to him when he is using CPAN as a user of libs from other users.

When I try to find something on rubyforge, the first thing that drives me 
nuts is, that I find a name and a more, but often less informative 
description, and very often no code. That last never happens on CPAN, at 
least I have not seen something like that until now.

So after finding out, which projects really exist, you cannot browse the 
documentation and only very few of the projects provide a more or less 
informative project-homepage. And if they provide a homepage, each looks 
different and for each one you have to find out, where the information 
is, you are looking for. (There are even people, who use blog-entries as 
homepages).

So to decide, whether the project could be useful to me, I have to 
install it and read the generated documentation. So my CPAN for ruby is 
'gem server'.

But even here the documentation is very different in quality. You can be 
very happy, if most of the methods are documented, but even then, it is 
very often hard to find out the big picture.

So at the end you spent a lot of time and you are not quite sure, whether 
you found the right package since this depends strongly on the quality of 
the description and wether they then show up in the search you did.

On the other end, browsing CPAN is real fun, even if you are not 
searching for something. And this is because (I think) the way CPAN 
presents the packages. If you publish something here, you do not want to 
be ashamed for not to provide at least a minimal useful documentation. 
Big projects even provide tutorials etc., which provide even more then 
just a brief API-documentation.

But when I write all this, it will become more and more clear to me, that 
it makes no sense to blame rubyforge for this, since as the name 
indicates, it is more ment to be something like sourceforge than CPAN. So 
what Ruby is missing is at all, is something, that might be called CRbAN.

Regards,
Thomas