In this post I'll argue that you should provide a concise, clear and informative abstract for your module: what that means, and why you should do it. Think of your module's abstract as the shop sign that passersby use to decide whether they should come in.
The abstract for a module is defined in the NAME section of your pod documentation. For my Module::Path module, this is:
=head1 NAME
Module::Path - get the full path to a locally installed module
Think of this as the one-line description for your module — this might be the only thing someone sees, and might affect whether they choose to look at your module more closely.
MetaCPAN displays the abstract prominently:
The recent list on search.cpan.org displays just the abstract:
Here are my thoughts on writing the abstract:
The abstract might be the only thing a potential user sees before deciding whether to look any closer. Treat it as your elevator pitch. It should make clear what your module does, and also what it doesn't do.
Perl Best Practices says the abstract should be a "one-line description of module's purpose".
Here's a counter-example, the abstract for OX
OX - the hardest working two letters in Perl
Ok, that's a funny line, but not a helpful abstract.
One good reason for keeping the abstract down to a single line is that search.cpan.org will only disply the first line of your abstract.
You should really try and keep it under 80 characters: look at how the abstract is displayed in MetaCPAN, and search.cpan.org.
It will be displayed as the title for your module, so treat it as such.
For example, if your abstract was "handling passwords", does that mean generating random passwords, encrypting and decrypting of passwords, checking the strength of passwords, or something else?
A good example is the abstract for Markdent
Markdent - An event-based Markdown parser toolkit
I see a lot of modules with an abstract of the form "interface to Foobar", which makes me wonder what Foobar does. For example, the abstract for Cairo used to be:
Cairo - Perl interface to the cairo library
I suggested the following:
Cairo - Perl interface to the Cairo 2D vector graphics library
This could be further improved by dropping the 'Perl' (see below).
A large number of (potential) perl programmers aren't native English speakers, so your abstract should be clear and simple.
Almost all of the places where the abstract will appear, the perl context is obvious.
The main potential counter-argument is that someone might find the MetaCPAN page for your module in a google search, and then the perl context might not be obvious. If they go look the MetaCPAN page there isn't anything obvious saying "this is perl stuff". Maybe I'll raise that as an issue.
But overall, I think you shouldn't include "perl module for", as that frees up space for more useful words. My thinking on this one has evolved slowly.
comments powered by Disqus