7.1. Types of Documentation

Distinguish user documentation from technical documentation.

End users will rarely read your code, or your comments. If they read anything at all, they'll run your module or application through perldoc^[] and read whatever emerges. On the other hand, maintainers and other developers may also read your POD^[*], but they'll spend far more of their time looking directly at your code.

^[] perldoc is a command-line utility that comes standard with Perl. It locates, extracts, and presents documentation from the Perl manpages, the standard library, and any other modules installed on your system. A good place to start is:

    > perldoc perldoc

^[*] POD is the "Plain Old Documentation" format, a simple mark-up language for embedded documentation that is recognized by the Perl compiler. If you're unfamiliar with it, take a look at the perlpod manpage.

So it makes sense to put user documentation in the "public" sections of your code's POD (i.e., in the =head1, =head2, and =over/=item/=back sections), and relegate the technical documentation to "non-public" places (i.e., to the =for and =begin/=end POD sections and to comments).

More importantly, distinguish between the content of user and technical documentation. In particular, don't put implementation details in user documentation. It wastes your time and it annoys the user. Tell the user what the code does, not how the code does it, unless those details are somehow relevant to the users' use of that code.

For example, when documenting a set of list operations for users, tell them that pick( ) takes a list and selects one element at random, that shuffle( ) takes a list and returns a randomly reordered version of that list, and that zip( ) takes two or more array references and produces a single list that interleaves the array values. You may choose to mention that pick( ) and shuffle( ) do their jobs in a genuinely random and unbiased manner, but there's no need to explain how that miracle is achieved.

On the other hand, your module may also provide a set of specialist sorting routines: sort_radix( ), sort_shell( ), sort_pigeonhole( ). When documenting these, you will obviously need to at least mention the different algorithms they employ, and the conditions under which each might be a superior choice.