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??

There are a number of lovely extensions to the core CPAN and PAUSE infrastructure: searching, browsing, viewing, rating, discussing, annotating, bug tracking, automatic testing, and archiving.

Nonetheless, I think there's room for one more: Guides. This includes module catalogs, comparison matrices, how-to guides and other articles about CPAN modules that are more general than a review/post/annotation of a single module or file.

Please let me know what you think of the solution proposed below.


CPAN::Guides - CPAN Recommendations and Commentary


Visit, or from the command-line:
> cpanguide methodmaker Found 1 guide document: EVO1 - Survey of Class Builders > cpanguide template Found 1 guide document: PERRIN1 - Choosing a Templating System > cpanguide perrin1 NAME CPAN::Guides::PERRIN1 - Choosing a Templating System DESCRIPTION Everything you wanted to know about templating systems and didn't dare to ask. Well, not everything....


CPAN Guides is a hypothetical Perl community project inspired by AnnoCPAN and CPAN::Forum. CPAN Guides does not actually exist. As you look over the documentation, please consider whether you'd use it if it did.

About CPAN Guide documents

A CPAN Guide is a document about CPAN modules. Some common types of guides are:

  • A recommendation, naming an author's favorite CPAN modules with a comment about each.
  • A comparision, listing a bunch of different CPAN modules that perform a similar function, and explaining the differences between them.
  • A how-to guide, that shows how the author got several CPAN modules working together to accomplish something.
  • A tutorial, which supplements the documentation included with a module with more examples or alternate explanations.

Most often, guides are written by experienced users to help others discover and select the CPAN modules they need. If a guide is very short, or only refers to one or two CPAN modules, it is probably better to post it as a review, annotation, or forum question for the relevant distribution.

Here are some documents which serve as CPAN guides:

The standard way of representing a guide is as a documentation file in POD format. A guide document always includes some standard POD sections for the title, author, etc. placed above and below a more flexible amount of "content". Inside the content, the author refers to various CPAN modules by name, interspersed with their comments.

About the web site

The CPAN Guides web site manages these guide documents, and is intended to work with the existing family of existing CPAN sites.

When viewing a guide, the names of CPAN modules referenced in the guide are automatically highlighted and displayed with links to the existing CPAN distribution, documentation, ratings, forums, and annotations services.

For any CPAN module or distribution name, you can see a list of guides that refer to it. When viewing a guide document, you can see a list of other guides that refer to the same modules as the current one.

Authors can sign in to post guides, and edit guides they've previously written. (Web authentication is via bitcard accounts, like CPAN reviews.) Authors create guides by editing the title and contents; other information like the author's name and modification date can be filled in automatically.

For efficiency, the CPAN Guides site uses a simple database (SQLite?) to index information about the guide documents, like the titles, modification dates, modules mentioned, etc. A recent snapshot of the index database can be retrieved from the CPAN Guides site to allow clients to perform local searches.

About the CPAN::Guides distribution on CPAN

The CPAN::Guides distribution includes Perl code used by the server. Some of this code might also be useful to people writing clients or otherwise working with the guides information. For example, another CPAN site showing information about a particular module could use the index files to find and link to any related guide articles.


Gather Feedback

Do other Perl developers think this would be useful?

Are there better ways to address this issue?

Is it likely to be used often and widely enough to justify the work of setting up the infrastructure?

Build Site and Seed With Content

Look at source for CPAN forum and annotations and talk with authors about their experiences.

Invite the authors of useful existing documents to post them as CPAN Guides.


It would be helpful to have an additional layer of meta-services over the core guide 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.

Each of those will require some effort to get right -- unless we were naughty and made someone else do it for us...

If we automatically created and distributed each guide as a separate module on CPAN, then we could piggy-back on the existing distribution, browsing, ratings, forums, and annotation services.

If a dozen or so really good articles get mirrored this way, it wouldn't be much of an imposition on the CPAN architecture. However, if a thousand crappy distributions got published this way, other people are likely to view it as abusive.

In the simplest form, we could package up all of the guides on the site as POD files in one distribution and periodically post that to CPAN; you can't vote on individual files within the distribution, but at least we'd have the mirroring and forums support...

Topics and Keywords

Decide on how to organize the guides:

  • Is it sufficient to provide text search and check for modules/distributions that appear on related lists?
  • Do we need a simple topic list to group related guides together: web server, web client, XML, database, templating, class-building, file I/O, etc?
  • Should users tag the guide or individual modules with arbitrary keywords to allow some kind of folksonomy to emerge?


For a shopping equivalent, see Amazon's "So you'd like to..." guides and "Listmania!" feature.

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

For more on playing nicely with the rest of CPAN see The Zen of Comprehensive Archive Networks and threads like this one.

Replies are listed 'Best First'.
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.


    Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

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 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 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 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 all is quiet...

How do I use this? | Other CB clients
Other Users?
Others rifling through the Monastery: (7)
As of 2018-06-21 10:50 GMT
Find Nodes?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?

    Results (118 votes). Check out past polls.