Writing POD documentation and help for the program

Plain old documentation (POD) is a way to document a Perl script inside the script itself. The perldoc perlpod command will tell you more about POD documentation and its syntax. Good POD documentation means that users can access help for your program quickly and efficiently. Take the time to learn the POD syntax; writing manuals will be much easier. In addition, POD is compatible with a variety of manual formatters, so you can generate a plain text file, a UNIX-style man page, and a professional-looking LaTeX file from the same documentation. POD is a fairly limited format, but perfectly sufficient for most documentation needs.

Generally, the following sections should be present in POD documentation: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, RETURN VALUE, ERRORS, DIAGNOSTICS, EXAMPLES, ENVIRONMENT, FILES, CAVEATS/WARNINGS, BUGS, RESTRICTIONS, NOTES, SEE ALSO, AUTHORS, HISTORY (from perldoc pod2man, where you can find more information on each section; keep in mind that these are suggestions rather than imperatives).

Some programmers make the -h switch to their programs invoke perldoc on the program, so the POD documentation is printed out as if the user had typed perldoc whodunit.pl. The problem here is that a user doesn't want too much extra information from the -h switch. He just wants the synopsis and the list of options. Thus, it is better to write separate help handlers arising from the use of the -h switch:

# print_help: help handler, prints out help for whodunit.pl and exits
sub print_help
{
 # print the help itself
 print << EOHIPPUS;
 This is help for the whodunit.pl program.

You can pass options to whodunit.pl as command-line arguments.  For
example:

..../whodunit.pl -h
..../whodunit.pl -show suspects

List of options:

-h     : print this help

-show  : show the suspects, victims, or detectives (all of them if no
         second argument is specified)

-quiet : print no information other than the killer's name

EOHIPPUS
 exit;                                  # do nothing else, just exit quietly
}

Note the documentation of print_help itself. Also, the the appearance of the POD documentation and other online help is important. The first place a user goes is not the manual. It's much more convenient to use the -h flag, or look at the POD documentation. Note the alignment of the colons, the spacing between lines, and the overall neatness. Outward appearances do matter, often more than the actual functionality provided by the program. Well-written programs should have good documentation first and foremost.

Some programmers like to include POD documentation in their program instead of regular comments. Such POD comments begin with =pod on a line by itself (there are other options, explained in the perlpod documentation), and end with =cut on a line by itself. The =pod line tells the Perl compiler to stop interpreting everything until the =cut line, in effect excluding that block of text from the script itself. This is fine if your users are also programmers, but may confuse normal users who just want to look at the documentation for the script, not the comments for the code itself. This approach also scatters documentation throughout the code. Use it with restraint.