For general advice on how to document Perl code,
chapter seven ("Documentation") of Perl Best Practices is worth a read,
providing sound advice on separating user from technical documentation, how to subdivide your technical documentation, discursive documentation,
algorithmic documentation, commenting, and more.
See also Conway's "Create Standard POD Templates for Modules and Applications" suggestion
in Ten Essential Development Practices.
Some further documentation tips derived from Writing Solid CPAN Modules:
- Separate user versus maintainer documentation.
- Ideally, a CPAN module's documentation should cover: Tutorial and Reference; Examples and Cookbook; Maintainer; How your module is different to similar ones; Change log; Notes re portability, configuration & environment, performance, dependencies, bugs, limits, caveats, diagnostics, bug reporting.
- Document your module's errors in the user's dialect.
- Add tests to your test suite to verify that examples given in your module's user documentation actually work.
- Use Pod::Coverage to help ensure your module documentation is comprehensive.