Following on from Re^3: How to read CPAN documentation, I've been thinking more that it might be a good idea to recreate the Phalanx project, but for documentation rather than test suites.

For those unfamiliar with history, Phalanx was a project which identified 100 key distributions on CPAN, and improved their test suites, expanding them to cover testing more of the software's functionality. The initial aim of this project was to use those key distributions to function as a test suite for Ponie (a reimplementation of Perl 5 on top of Parrot, which is sadly no more), but side-effects were to improve the distributions themselves, improve the state of Perl testing tools, and establish those distributions as good examples of testing that other distributions could follow.

So let's do this for documentation!

How to go about it? I have a few initial ideas:

1. Identify the key distributions. This is not just about what's popular; there will be other criteria too. For example, rather than choosing both Moose and Mouse (and maybe Moo, or Mo), only Moose would be chosen, because if you have a good understanding of Moose, you'll be able to use the others straight away. The quality of their current documentation is not a factor here; some will no doubt already have great documentation.
2. Identify what makes great documentation great - let's call them the key criteria. This can be done in parallel with the previous task. Ask users what they need; and which modules are already well documented. Research outside the Perl community too. One thing that I imagine most users want is a good set of practical examples of the software being used.
3. Contact the maintainers of the key distributions asking them if they are willing to have the distribution included in the project. That's not to say that if they agree, then we'd be forcing them to include anything in the distribution that they didn't want to, but if they're flat out uninterested in it, then there's little point expending extra effort on the distribution.
4. Assess each of the key distributions for each of the key criteria. Give them a score from 0 to 4 on each (0 = no documentation on this criteria; 1 = poor/brief documentation; ...; 4 = awesome). Record this.
5. Write the documentation. In some cases the distribution maintainers themselves might do this, having seen the areas for improvement listed. In other cases we'd be sending them patches.
   • This is an important point: when writing example code for the documentation, include examples of the software working in conjunction with other key distributions. For example, if writing documentation for JSON.pm, if you need to do a bit of OO, then use the OO framework which is on the list of key distributions (which would presumably be Moose). Don't just try to document these distributions in isolation, but as part of the entire Perl+CPAN ecosystem.
6. Work with the people running MetaCPAN to better expose documentation on the Web. Many distributions already include "examples" directories, but they're not obvious.
7. And ummm... iterate. When all the key distributions are getting close to scores of 4 across the board on all the key criteria, then look at bringing in other distributions, and expanding to more criteria.

Optimistic outcomes:

• Better documentation for the distributions in question.
• More holistic documentation for using best-of-breed CPAN modules in conjunction with each other.
• Document how to write good documentation. Use our experience writing documentation for the key distributions to help other people document their software better.
• Publish the software we use to track the documentation status of our key distributions. There are niche communities within Perl (such as the BioPerl community) who may want to run smaller scale versions of this project.
• It will give people who don't publish CPAN modules themselves another route to contribute to improving what's on CPAN.

So how do we start? To begin with, I need other people. I lack the time and expertise to do this all. And I don't want to be the sole arbiter of which distributions and documentation criteria are "key". (Though I reserve the right to sway the decisions a bit.) Without at least ten people involved, this thing doesn't fly at all.

So if you're interested in helping, reply below, or contact me by e-mail at tobyink@cpan.org.