NEILB's Blog

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:

• It should describe what your module does
• It should be on a single line, and not too long
• Be as specific as you can
• Give as much context as you can
• Don't use idiomatic or colloquial English
• Don't include "perl module for"
• You don't need a full stop (period) at the end

Describe what your module does

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.

Single line

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.

Be as specific as you can

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

Give as much context as you can

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).

Don't use idiomatic or colloquial English

A large number of (potential) perl programmers aren't native English speakers, so your abstract should be clear and simple.

Don't include "perl module for"

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.