Give your modules a good abstract

If you're looking for something to release on CPAN day, check the abstract for your modules, and make sure they have a good abstract. The abstract should not only be compliant pod, but should succinctly describe what your module does. The name and abstract are often the first thing that potential users see, so make them count.

The first heading in your pod should be the abstract, or the NAME section. Here's an example:

=head1 NAME

Business::CA::GST - Look up Canadian Federal Sales Tax rates

There should be a blank line between the two content lines, and the abstract is a paragraph that should match /^$module_name - .*$/.

Some additional suggestions for good abstracts:

  • Don't start it with "perl module for", as that's redundant. So "Module for uploading images to" would be better as "upload images to".
  • In general you shouldn't see the word 'perl' in the abstract, apart from in abstracts like "Pure-Perl non-blocking I/O MongoDB driver".
  • Try to keep it under 80 characters: it's going to be presented in search results, on recent releases pages, and in other summaries.
  • Make every word count: "A tool to make it easier to manage multiple code repositories using different VCSen" would be punchier as "Easily manage multiple git repositories". Don't use words like 'fast' unless you've benchmarked against competing modules to back it up.
  • Remember that some of the people reading it will be new to CPAN, so stick to clearly communicating what the module does. Instead of "A drop-in replacement for Getopt::Long, with tab completion", "Command-line parsing with tab completion (Getopt::Long compatible)" describes what it does, retains the Getopt::Long mention, and is only a handful of characters longer. Acme modules obviously get a pass on this one :-)

Some of these are down to personal preference; if you disagree with me, fair enough. The main thing is to pay attention to the abstract.

Before CPAN Day, check the abstract of all your modules, to see whether you can improve any of them. The easiest way to review the abstracts for your distributions is to start off by looking at your author page on MetaCPAN.


> Don't start it with "perl module for"

One thought; the documentation may not be aimed exclusively at CPAN. E.g. many people use their POD on github too, where it seems sensible to state that the module is for Perl

Leave a comment

About Neil Bowers

user-pic Perl hacker since 1992.