Perl Documentation in Terms of Tasks

The core Perl community—if you care to draw lines around a group of people who use Perl seriously and call that a community—is like many other core F/OSS communities. Real work happens on mailing lists and IRC. I unsubscribed from several mailing lists and deliberately spent as little time on IRC as possible this year, for various uninteresting reasons. (I haven't even made it to the Portland Perl Mongers meetings for several months.)

While that's been good for my productivity, it's also produced an interesting sense of disconnect, and that makes me wonder. Consider a thought experiment. Suppose you have six months to build a new green-field project. Your primary language is Perl. You're the only developer on the project, but you do have coworkers to do some of the non-coding work. You don't have access to IRC or mailing lists, but you do have access to the whole of the CPAN. In other words, your social connections are limited but your technical decisions are not.

In this situation, how do you find the best libraries and techniques to use for your requirements and how do you solve problems and get your questions answered?

Assume you have access to web forae such as PerlMonks and Stack Overflow and of course Duck Duck Go.

I can answer this partially for me: thank goodness for the degree of maturity the CPAN and its ecosystem encourages among its best projects. I have a lot of confidence in the stack I've chosen of Moose, Plack, DBIx::Class, and Catalyst, sprinkled liberally by great new tools such as perlbrew, cpanm, and Try::Tiny—but even so, the documentation and community support available without real-time discussion with contributors and developers isn't always sufficient to solve problems quickly.

(How interesting to note that all of these tools hew from a post-Perl 6 world, and how any Perl 6 implementation as it stands now only barely obviates the need for part of two of the named projects and deigns even to consider the others.)

For example, what's the best way to manage passwords and authentication in a Perl-based web application? Do you handle it at the Plack level or the Catalyst level? What if your user table doesn't match the example in the Catalyst authentication plugin example? How much better is bcrypt than SHA-1 or SHA-256? What if your business requirements mandate that users verify their accounts before they can login? How do you modify/subclass/extend/advise the plugin you use to meet this requirement?

Anyone who's done a few projects with this stack should be able to give a good answer to these questions, as should anyone who's spent a few weeks in the relevant IRC channels or a couple of months reading the right mailing lists. They're not difficult questions, but they are detailed questions. You could ask the same questions about the right way to manage DBIC schemas you expect to deploy frequently while allowing for schema updates and changes.

The interesting question isn't how to accomplish these things, it's how someone finds this information without mandating access to IRC or the mailing list.

I make the assumption that it's valuable to have multiple sources of information. We write copious documentation including ::Manual and ::Tutorial PODs in our top-level distribution namespaces, after all. We do an admirable job of producing Perl Advent Calendars (thanks, Andrew Grangaard!), but I'm very glad to see Catalyst retiring its calendar in favor of monthly articles. Publishing on a schedule is difficult, but the need for current information is present the other eleven months of the year.

I wish I could say that Perl and project wikis were more useful, but they seem neither popular nor currently useful to me. Maybe I looked in the wrong places. (I know I promised to give Catalyst a list of questions about things that weren't screechingly obvious; I have a list, but I haven't shown it yet. I have patched a few parts of the Plack documentation.) Yet it seems to me that for all of the energy and output of the core Perl community, the practical non-code results tend to be directed in ephemeral directions. In the past couple of months, people such as Gabor Szabo and Christian Walde spent a lot of time to improve the results for searching for "Perl tutorial" by creating a central place to list and evaluate Perl tutorials.

Again, maybe I looked in the wrong places—but I'd like to see a 2012 focus on making the knowledge and experience of core project members available further, in many other media. always welcomes your submissions of course, but that's not the only persistent and updated medium for project knowledge.

If we want people to use our code and projects for real work, to solve real problems, and to accomplish real tasks, we need to continue to provide practical code and useful documentation at or above the high quality level we currently enjoy. Yet we also have to work to approach this audience from their point of view: in particular, in terms of the tasks they want to accomplish.

That is the resolution I suggest for the Perl community in 2012.

Modern Perl: The Book

cover image for Modern Perl: the book

The best Perl Programmers read Modern Perl: The Book.

sponsored by the How to Make a Smoothie guide



About this Entry

This page contains a single entry by chromatic published on December 26, 2011 12:01 PM.

Don't TSA That Data! was the previous entry in this blog.

Interested in "The Year in Perl"? is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.

Powered by the Perl programming language

what is programming?