<title> RFC: CPAN::Guides </title>

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:

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:

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:


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.