Chapter seven ("Documentation") of Perl Best Practices is well worth a read, no matter what language you are using, providing sound advice on separating user from technical documentation, how to subdivide your technical documentation, discursive documentation, algorithmic documentation, commenting, and more.