|Public Scratchpad||Download, Select Code To D/L|
<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
SYNOPSISVisit www.cpanguides.org, 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 www.cpanguides.org 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 cpanguides.org 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.
TO DO / QUESTIONS
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:
- Collects and maintains votes or ratings to promote the most useful lists.
- Provide a mechanism for other people to post comments 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.