Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot

RFC: CPAN::Guides

by simonm (Vicar)
on Jul 25, 2005 at 03:28 UTC ( #477668=perlmeditation: print w/ replies, xml ) Need Help??





CPAN::Guides - CPAN Recommendations and Commentary


Visit, or from the command-line:



About CPAN Guide documents




Here are some documents which serve as CPAN guides:


About the web site






About the CPAN::Guides distribution on CPAN



Gather Feedback

Do other Perl developers think this would be useful?

Are there better ways to address this issue?


Build Site and Seed With Content





  • Collect and maintain votes (or ratings?) to promote the most useful lists.
  • Provide a mechanism for other people to post comments (or annotations?) in response to a guide.
  • Downloads, version history and diffs between various changes.





Topics and Keywords

Decide on how to organize the guides:




Similar CPAN extension projects include CPAN::Forum and AnnoCPAN.


Comment on RFC: CPAN::Guides
Download Code
Re: RFC: CPAN::Guides
by xdg (Monsignor) on Jul 25, 2005 at 11:53 UTC

    It's a very interesting suggestion, but I wonder if it's trying to introduce yet another source of information into an already crowded space. Much of this already exists here, for example. To play devil's advocate:

    • If documentation is in POD format, why shouldn't authors just upload .pod files to CPAN under an appropriate hierarchy point (e.g. CPAN::Guides::Foo) instead? This would have the advantage that the guides would be searchable using existing tools ( and could be downloaded to be read locally using perldoc. (Plus bundling, annotations, ratings, bug trackings and all the cool stuff already on CPAN.)
    • Why will this site attract authors more than existing venues like Perl Monks?
    • What about encouraging perlmongers groups to seek out authors and get their permission to convert articles elsewhere to POD for posing on CPAN?

    Overall, I think it's a worthy idea to get more guides into a single, searchable repository. I just think that it would be easier to use the repository we've got, rather than build another one. A "" site could still be built on top to provide more guide-specific searching than the standard CPAN search tools.



Re: RFC: CPAN::Guides
by siracusa (Friar) on Jul 25, 2005 at 12:26 UTC

    I think the CPAN module author/ownership is the wrong model for CPAN guides. I'd rather see something Wiki-ish where anyone can update the information--not just annotations or comments, but the actual content.

    Most of the example guide documents you cited are already a bit out of date. (New CPAN modules come out all the time.) It'd be nice if anyone could update the guides, instead of relying on the original authors for everything.

Re: RFC: CPAN::Guides
by Anonymous Monk on Jul 25, 2005 at 13:12 UTC
    CPAN Guides is a hypothetical Perl community project inspired
    That's a failure from the start. By assuming your suggestion will be a "community project", not much work will ever get done. Community projects are (large), existing projects, that already have proven to be worthwhile. Perl didn't start as a community project either, instead, it started as the project of one man. Who slowly got a few people to supply patches, and only after a long time, it because a community project.

    If you think this suggestion has merit, start working on it. Build the infrastructure. Set up your website. If "the community" likes it, it'll embrace it and turn it into a "community project". If not, oh, well. Too bad.

      For those who aren't familiar with the concept hinted at above by the Anonymous Monk, you might want to take a look at articles about the bystander effect. (and by extension, social loafing, diffusion of responsibility and pluralistic igorance).

      Essentially, people in a group will be less likely to act, as they don't want to stand out, and will prefer to wait for someone else in the group to act. Anyone who's done work on a poorly managed project has probably seen this -- people become apathetic the goal of the project, (it might be that they don't want to be judged as sucking up, or they don't see why they should do more work than the others, but for whatever reason, without proper management, less work gets done).

      The only way for a project to work is for there to be a clear delineation of responsibility -- every task needs to have a single person responsible for it, so that they don't think that someone else is going to do it, and they shouldn't bother. If the project team is only one person, that means that that one person does everything.

      I've been involved in a couple of 'community projects', where too many people were taken on before we had a chance to get the framework set up -- it actually hinders the project, when you have to tell people 'no, we're not ready yet', because we didn't have the necessary infrastructure, and by the time that we did get the right stuff in place, they were disinterested because of the earlier stalling.

      I'd recommend the same thing that the anonymous poster already said -- start the project, and set up the infrastructure. Identify what parts you're willing to cede control of, and that you can pass off to another person without going through a lengthy training period or otherwise need them to keep contacting you. (so you don't get the point where you wonder if it'd just be easier to do everything yourself, if you're going to have to watch over their shoulder, etc.) This isn't an overnight project... this could be a very useful project, but it's going to take more work than 'here's my idea...someone else go do it now', which I've seen other projects try.

Re: RFC: CPAN::Guides
by Smylers (Pilgrim) on Jul 25, 2005 at 13:36 UTC

    Many people over the years have suggested something like this. The hardest part is actually coming up with the content: writing decent docs, especially comparisons, is time-consuming and hard.

    There's no point in having lots of infrastructure if there won't be the content to go in it.

    Or to put it another way round: your suggestion seems to be a solution to the problem of us having too many decent guides and comparisons but nowhere to put them. I don't believe that's currently a problem we have.


Re: RFC: CPAN::Guides
by brian_d_foy (Abbot) on Jul 25, 2005 at 17:18 UTC

    I don't think CPAN Guides will help people who need it. Someone unfamiliar with CPAN or the myriad Perl forums won't know the name of the module or author to look up. They probably won't know about the many resources already available, and I expect they won't know about yet another resource. If they can't use CPAN effectively already, I don't expect them to find a CPAN Guide module on CPAN.

    I've seen a lot of these proposals over the years and they follow a certain trajectory usually: a lot of people get excited about the infrastructure, spend a little time working on a database, and then end up moving on. Any time you start thinking about the distribution mechanism first, you're likely to not get anywhere.

    There are already a lot of places that people can get information about modules, types of modules, and so on. The trick is to produce more content and make it available through a canonical source, such as CPAN Search which already links in a lot of information about modules.

    I'd certainly be happy to publish new content in The Perl Review. :)

    brian d foy <>
      such as CPAN Search

      I think you wanted CPAN search. What a difference one letter makes :-)

      Update: Parent node has been updated.

Re: RFC: CPAN::Guides
by itub (Priest) on Jul 25, 2005 at 18:12 UTC
    One could argue that the 2nd Ed. of Advanced Perl Programming is basically a CPAN guide on paper. ;-) And many articles on The Perl Journal, The Perl Review, and are also CPAN guides of some sort, although in the first two cases they require subscription.

    I think such a site would be useful but, as others have said, the trick is producing the content. If you just create a blank site and expect people to contribute, you are likely to be disappointed. You are more likely to succeed if you seed the site with a good amount of content and make it easy to contribute. And you need to make sure that the site remains alive and kicking, even if you have to write the guides yourself. Otherwise the site may end up being forgotten, like the CPAN wiki at which hasn't had any update in months.

    The listmania idea sounds interesting; it would be a good way of knowing which modules are more popular. There have been informal threads about it here (for example, "Desert island modules 472458), but it's much harder to count the results without the infrastructure.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://477668]
Approved by Tanktalus
Front-paged by kvale
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others taking refuge in the Monastery: (6)
As of 2014-12-27 15:10 GMT
Find Nodes?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?

    Results (177 votes), past polls