DEV Community

Cover image for CPAN Module Tutorials
Dave Cross
Dave Cross

Posted on

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.

Top comments (3)

Collapse
 
szabgab profile image
Gabor Szabo • Edited

Why maintain another site?

Wouldn't it be the best to use this CSV file to create page(s) on MetaCPAN and include links to those pages from the respective articles?

OR to embed the links on the documentation of each relevant module?

There could be some script monitoring the web sites to notify the maintainer of the CSV file in case a page is gone or it is change to something else.

If you really want to put this on a separate site, I'd generate static pages from the CSV file and use GitHub pages to host it.

Collapse
 
davorg profile image
Dave Cross • Edited

Why maintain another site?

I'm not maintaining another site. I'm using GitHub to gather data and convert that data into a more useable format.

Wouldn't it be the best to use this CSV file to create page(s) on MetaCPAN and include links to those pages from the respective articles?

I think the MetaCPAN team are planning to use this new data to add article links to the distribution pages.

OR to embed the links on the documentation of each relevant module?

That relies on responsive CPAN authors. And I don't think we can guarantee that.

There could be some script monitoring the web sites to notify the maintainer of the CSV file in case a page is gone or it is change to something else.

There are plenty of enhancements I'm planning. That's one of them.

If you really want to put this on a separate site, I'd generate static pages from the CSV file and use GitHub pages to host it.

That's pretty much what I'm doing. Except there's not a site - just a JSON file.

Collapse
 
szabgab profile image
Gabor Szabo

OR to embed the links on the documentation of each relevant module?

That relies on responsive CPAN authors. And I don't think we can guarantee that.

I meant by MetaCPAN - not relying on the authors.