Give your module a good SEE ALSO section

The SEE ALSO section in your module's pod is where you direct the reader to other things of interest. In this post I'll briefly outline what constitutes a good SEE ALSO, and why it benefits you to create one.

My thoughts on this topic have evolved over time, and in writing this I've realised that a lot of my modules could do with a brush up. I'll be releasing those on CPAN Day, of course :-)

There are a number of different things you can present in your SEE ALSO:

  • Other modules that provide similar functionality (aka competitors).
  • Other modules that might be used together with your module.
  • Other modules that are part of the same distribution.
  • Sources of related information, such as wikipedia pages, published papers, etc

Personally, I think the following things don't belong here:

  • Listing the modules that your module uses (ie dependencies). In MetaCPAN they're already listed in a right-hand sidebar, so you shouldn't duplicate them. One exception is where part of your module's interface is provided by the dependency.
    • A lot of older modules list(ed) "perl(1)" and similar.

Golden rule: make things links

When listing other modules, make them links:

=head1 SEE ALSO


MetaCPAN, and other sites will make these hyperlinks.

When giving a URL, you can give link text:

See the L<wikipedia page|>
for a description of the algorithm.

You can read more about the L<> formatting code in the perlpod documentation.

Listing your competitors

First you need to find the other modules that provide similar functionality. This isn't always easy, but the distribution search on is a good place to start. I also grep 02packages.details.txt, but realise that's not for everyone.

Once you've got a first list of modules, look at their SEE ALSO sections, to see if there are other modules you've missed. Usually this comes down to namespaces you hadn't considered, and searching those namespaces can turn up more modules.

As a start, you can just give a list of links (eg as in Lingua::EN::Numbers):

=head1 SEE ALSO

L<Foo::Bar>, L<Foo::Baz>, L<Delicious::Marmite>.

But it's even more helpful for CPAN users if you give a small summary of each module, focussing on how it differs from yours.

L<Foo::Bar::XS> provides the same interface,
but is much faster (because it's written in C).
The downside is that you need a compiler.

As an example, look at the SEE ALSO for Text::Levenshtein, which I added when I adopted the module.

If there are a lot of modules, then you might give a summary of the main contenders, and then just list the others (as links, of course!).

So, why bother doing all this?

  1. It helps people who are looking for something on CPAN. Your module might be awesome, but another module might provide the specific function someone is after, or maybe you have too many dependencies for them, or ...
  2. It aids discoverability. Listing other modules makes it more likely that your module will be found. For example, if you search for Path::ScanINC on MetaCPAN, you'll see my module Module::Path listed in the results. That's because I list Path::ScanINC in the SEE ALSO section.
  3. Looking at your competitors can improve the way you think about / code / document your module, and give you ideas for new features.

In my dream world, whenever someone has an idea for a module, they start by writing the SEE ALSO section. By the time they've done that, they either decide not to bother, or they have a better concept of what ecological niche they're going to occupy. Bwahahaha!


Apart from the fact of you flooding my TODO list ;-) I can only say it is good advice.

I myself do however have the practice of making a DEPENDENCIES section in addition to SEE ALSO so you can list dependencies as a part of the documentation, this is also the recommendation from the Perl::Critic policy ( and PBP (if I remember correctly). MetaCPAN is not necessarily the only place where documentation is presented.

Looking forward to CPAN day, take care,


Now that we have META.yml/META.json the DEPENDENCIES section is quite irrelevant as it is not as powerful as the raw data. Sites like MetaCPAN can process META files to render them for humans, even for modules that don't have the DEPENDENCIES documentation.

I rarely write a DEPENDENCIES section, but I did for Type::Tiny, and it's more than just a duplication of the right-hand column on metacpan.

Wouldn't it be even better to have an entry in META.json listing the related modules?

Something to remember for all of Neil's excellent posts in this series - if you don't have any distributions of your own that you can patch, you can patch other people's distributions!

Leave a comment

About Neil Bowers

user-pic Perl hacker since 1992.