From: Peter Hickman <peter@...>
Date: 2008-08-06T18:33:40+09:00
Subject: Re: perl and the culture of libraries

A critical thing for me is that when programming Perl the POD usually 
contains sufficient information and *EXAMPLES OF USAGE* to throw the 
basics of an application by simply cutting and pasting from the POD. The 
Ruby documentation is wonderful when you know what you are doing and 
just want to brush up on the details but practically useless if you are 
new to it. This discourages people who might have an interest in the 
project but don't have the time or skills to work out what is going on 
from the source.

Just as an example ANTFARM for just announced, the synopsis from the 
post was:

NAME

 ANTFARM

DESCRIPTION

 Passive network mapping tool.

URI

 http://antfarm.rubyforge.org
 http://rubyforge.org/projects/antfarm

INSTALL

 gem install ANTFARM

HISTORY

 0.2.0
  - Initial release as open source

SYNOPSIS

 $> antfarm help


Not discouraged I went to the project page which was just as helpful. 
Then I walked away. Now ANTFARM maybe the coolest project there is (it 
recalled to me the use of ALife 'ants' to optimise network routing which 
was why it piqued by interest) but I don't have a fucking clue about how 
to do anything with this project. Other than you initialise it with 
"antfarm db �initialize". Sometimes people shoot themselves in the foot, 
others seem to go for the head.

I'm not picking on the ANTFARM team in particular there are plenty of 
projects, both Ruby and non Ruby, that assume that you are psychic or 
like wading through the source code as some sort of rite of passage. 
This project seems to be completely free of vapour judging by the amount 
of code that has been developed but it is almost as if they are actively 
trying to drive potential users away.

*EXAMPLES OF USAGE* people, were need more of them!