Putting It All Together

The Perl community gets a lot of things right right now. Consider the CPAN: we expect a few standards of compatibility and kwalitee, but as long as you adhere to rough consensus, your work is useful and usable to a million other Perl programmers.

We have a good understanding of how to package your work and how to mark dependencies and how to document it, and that rough consensus allows sites such as search.cpan.org to provide infrastructure that allows me to read cross-linked documentation of the 84,944 modules on the CPAN (as of this afternoon).

Even the standard documentation mechanism for Perl modules (POD, adhering to a loosely-agreed organizational scheme) contributes to the utility and usability of the Perl ecosystem. You expect perldoc Your::Distro::Name to display something useful for the distro, even if it's a table of contents to other documentation. Larger projects or frameworks have introductions and tutorials and guided recipes (you know, like a "book" for "cooking", except without infringing on a trademark). If you know what you're doing and need a mere syntax refresher—or if your problem is small enough that a handful of lines of code can solve it—the SYNOPSIS section of the documentation is often enough.

Other times it isn't. Explain Plack in a paragraph, or DBIx::Class, or Perl::Critic, or Bread::Board (or explain Bread::Board at all; sometimes I think Stevan and Yuval are the only people who understand it).

Many of the wonderful new tools I want to use in Perl right now have a steep learning curve. I understand that some of them (Devel::Declare) have essential complexity that users must master before using the tool effectively. Not everything does—look at Test::Tutorial, which takes a subject which seemed complex and confusing in 2000 and 2001 and is commonplace and expected in 2010. Writing effective tests well is still an art of experience and good taste, but half an hour with that documentation has been enough to explain the basics to thousands and thousands of people.

I recognize that a SYNOPSIS won't suffice for demonstrating even a simple Catalyst application, with user authentication and logging and route dispatching and a model which is more complex than a Blog with Posts and Comments, but perhaps there's something in between a "Hello, world!" tutorial and the gory documentation of individual components and their methods. (Catalyst does this better than almost every other CPAN project.) Maybe larger projects should consider guided walkthroughs of real and modest-sized applications, especially if they include discussions about design goals and tradeoffs.

We're good at documenting reusable pieces of larger systems—CPAN encourages us to build applications that way. Can we improve further?