NeilB

The DESCRIPTION section of your module's documentation should come after, and provide the narrative for, the SYNOPSIS. In particular, make sure that the first paragraph is a good summary of what your module does / provides. After the abstract, the first paragraph is your most powerful tool in selling your module to potential users.

For CPAN Day (next Saturday 16th August), make sure all your modules have a DESCRIPTION section in the pod, and that the first paragraph is a good summary. And if you do, tweet about it, using the hashtag #cpanday.

If you search for Module::Path on MetaCPAN, here's how my module appears in the search results:

The module name and abstract make up the first line, then the summary of the module is taken from the start of start of the DESCRIPTION section (approximately the first 250 characters). You can see that the first paragraph of your description is important. I can definitely improve on that, and will be reviewing all of my dists.

As an aside, here's the same thing from search.cpan.org:

It only uses the abstract, so really make that count. For example, compare and contrast with:

Non-descriptive top-level namespace and content-free abstract. Most people can't get away with that, but perhaps DOY can? ;-)

Sometimes the start of the DESCRIPTION is fine when read in the context of the page, but not so useful when seen out of context:

If your module doesn't have a DESCRIPTION section in the pod, then no summary will be presented. Here's an example:

Lest you think I'm picking on OLIVER again, I've sent him a bug report for this, which will hopefully result in a release on CPAN Day :-)