Give your modules a good SYNOPSIS
If the abstract for your module is up to snuff, then have a look at the SYNOPSIS to see whether you could improve that in a CPAN Day release. The SYNOPSIS should briefly show typical usage of the headline features of your module.
Here are some guidelines for a good SYNOPSIS:
- Keep it brief. You don't need to show everything about your module.
- Make sure the code presented actually works.
- If there are logically different sections to the SYNOPSIS, break it into multiple code blocks, with a lead-in comment for each.
A bit more on each of those in turn.
Keep it brief
The SYNOPSIS shouldn't try and demonstrate every last feature. Instead, aim for the smallest example that illustrates the core essence of your module.
Have a look at the SYNOPSIS for Moose: Moose has a lot of features, but the SYNOPSIS just shows a simple class and a subclass.
Personally, I don't think you should include
use strict; and
use warnings; in your SYNOPSIS, unless it's relevant to your module (as with strictures). It should be a distilled example, with no distractions. Opinion's split on this point though, so decide for yourself.
Minimise any comments you include, lining them up off to the right, if you can. You can give longer examples in body of the documentation.
Make sure the code works
It's frustrating if someone copies the SYNOPSIS and it doesn't work. Sometimes it's down to a simple syntax error, but sometimes it's because the interface has changed but the SYNOPSIS wasn't updated.
I like the idea of a DZ plugin that extracts the SYNOPSIS from one or more test files.
Split different concepts into different sections
If there are distinctly separate concepts to your module, then split the SYNOPSIS into multiple sections. A good example where this makes sense is exporter modules: have one code block that shows the exporting module, and another that shows the importing code. A good example of this is Sub::Exporter.