The Best Practices suggest putting your documentation in your source files, and provides some reasons. This is okay.
The reasons given for putting the docs in the sources include keeping it all together for when the user installs it. Installing Perl stuff is hard enough, just what we need is to spread that documentation around further. As far as that goes, I agree with the suggestion. Your POD belongs in your source code.
If you have other documentation, it might not. POD makes good reference documentation, covering every module and function. It is less good for overviews and user’s guides and FAQ’s. Of course it can do those things, and has been used for them. HTML or a format better suited for distribution on the web or for print may be more useful. If you’re working on a collaborative project, some of that documentation is probably on a Wiki.
Different kinds of docs might go in different places. But the reference docs that document every function work well in POD, and that belongs in your source module.
One option is you can use Pod::Simple::HTMLBatch to generate html pages from pod (this is what cpan.org does).
A virtue of pod is that if you’re using the cpan toolchain, the documentation gets installed as man pages (at least on a unix box, I don’t know what windows does with it).
One area where I disagree with Conway, by the way, is that he’s a pod-at-the-bottom kind of guy, and I’m a big believer in distributed pod– ever sub should have it’s documentation by the sub. But then, I’m pretty sure I’m the kind of guy who thinks in English primarily, so it’s natural for me to write docs first, then fill in the code (ideally after writing some tests). As you mention elsewhere, programmers like to fight about things like this and it seems as though there’s a real difference in the way some of us think (e.g. clicking over to code brain, where English gets in the way).
I think POD at the bottom is better than in between code because it lets you structure the POD more naturally rather than contriving it to have the same structure of the code, e.g. you may want to order things differently in code and in POD, to some degree. Also many sections in POD don’t directly correspond to parts of code, so how do you arrange those mutually. So I think POD should all be together, at the bottom. Or alternately have the POD in a completely separate file, e.g. you can have Foo.pm and Foo.pod side by side in a distro if you want, and that also gives you the option to split the POD into a different number of files than your source code, so each is arranged more naturally.