CPAN Module Tutorials

Here's a nice little project that went from a good idea to something useable in a couple of hours.

We all know (I hope) that there are lots of great libraries available on MetaCPAN. What isn't sometimes quite as obvious is how to use those libraries. The documentation is usually a pretty good reference but in many cases, what you really want is a good tutorial. And they seem pretty rare on CPAN.

There are, however, hundreds of good tutorials out there on the web. But that doesn't really help the people looking for documentation on MetaCPAN.

Yesterday there was a discussion on the TPF Slack about this very problem. Olaf Alders (who leads the team behind MetaCPAN) said that he would be happy to link to quality posts about modules that are on other sites.

This sounded interesting to me. And I started thinking about a web app where users could submit links to tutorials. The site would then produce an API which MetaCPAN (or, indeed, anyone else) could use to add links to those sites.

I was thinking about a Dancer2 app. Which would require users and authentication and hosting and all the stuff that comes with a web app. But then we realised that (at least as a proof of concept) none of that was actually needed. We could do it all on GitHub.

So now we have LearnCPAN. It's just a CSV file with three columns (distribution name, tutorial URL and tutorial title). If you want to submit a new tutorial, then you can simply create a pull request against the repo. Once your PR is merged, there's a simple GitHub Action which parses the CSV file and produces a JSON file which MetaCPAN can use to add tutorials to a distribution's page.

I've seeded the CSV with a couple of years of examples from the Perl Advent Calendar. But it's ready to take your submissions now.