NeilB

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

L<Acme::CPANAuthors::YakShavers>

MetaCPAN, search.cpan.org and other sites will make these hyperlinks.

When giving a URL, you can give link text:

See the L<wikipedia page|http://en.wikipedia.org/....>
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 search.cpan.org 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!