Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

perldoc plus plus

by tobyink (Abbot)
on Jul 06, 2012 at 20:54 UTC ( #980375=perlmeditation: print w/ replies, xml ) Need Help??

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.

perl -E'sub Monkey::do{say$_,for@_,do{($monkey=[caller(0)]->[3])=~s{::}{ }and$monkey}}"Monkey say"->Monkey::do'

Comment on perldoc plus plus
Re: perldoc plus plus
by perl.j (Pilgrim) on Jul 07, 2012 at 02:40 UTC

    I love the idea.

    I would be interested in helping. I cannot say I will be extremely helpful/active, but I can help.

    --perl.j

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others having an uproarious good time at the Monastery: (6)
As of 2014-08-30 23:16 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The best computer themed movie is:











    Results (294 votes), past polls