Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.
If this question can be reworded to fit the rules in the help center, please edit the question.

8 Answers
8

Look inside almost any Perl module and you'll see the Plain Old Documentation (POD) format. On CPAN Search, when looking at a module you have the option of viewing the raw source, so that's one way you can look at the raw pod, but you can also use perldoc from the command line. The -m switch shows you the file

perldoc -m Foo::Bar

Or, if you want to find the file so you can look at it in your favorite editor, use the -l switch to find it:

perldoc -l Foo::Bar

Once you start documenting your program, you put the Pod in the file right with the code, either interwoven with the code so the documentation is next to the relevant parts, or at the beginning, middle, or end as one big chunk.

Pod is easily translated to several other formats, such as LaTeX, Postscript, HTML, and so on with translators that come with Perl (pod2latex, pod2ps, pod2html). I even have a pod translator that goes to InDesign. Writing your own Pod translator is easy with Pod::Simple, so if you don't find a translator to your favorite final form, just make it yourself.

Not to be overly flip, but the best way to document Perl code is the same way as you would document code in any other language.

As for specific tools, I use a mix of standard inline comments, pod for larger chunks of documentation where a format similar to man is appropriate, and TeX as a final fallback for documents that need to be more freeform. (And, in the spirit of "same as any other language", yes, I do use pod for documenting non-Perl code as well.)

This module is awesome. Kinda surprised I never heard of it before. Can't tell you how many times I've written subroutines to do parts of what this module can offer, can't recommend it enough.
–
slmOct 26 '11 at 1:39

seperate user docs and coders docs. maybe put user docs (tuts, faq, reference) in there directory (/doc) and coders in same as the code. unfortunately its expected by conventtion, to have overview in the module itself. this you can as already layed out do it POD after END. mane coding docs you can put in comments. additional things like coding style or how to contribute put in seperate .pod files inside the code base (root dir?)