Chapter 3

The reader is presented with a clear description of what the module is meant to do.

Here's an example of how not to describe the same module:

=head1 DESCRIPTION

This module will provide an interface to the BOA SETI satellite.  The

satellite communicates with the base station over a radio IP link.  The

module uses a low level UDP socket interface to communicate with the satellite

to maximize bandwidth utilization.  It also compresses larger packets with

Compress::Gzip for further saving.

This description also delivers useful information, but it leaves open the most 

important question what does the module do? It can be tempting to jump 

directly into implementation details; after all, that's where the fun of programming 

is. However, even the most technically minded reader would be hard pressed to 

figure out what BOA::SETI does from the preceding description.

Know Your Audience

Writing good documentation is a lot like any other kind of writing to do a good 

job you need to think about your audience. Your primary audience at this stage is 

actually yourself. The best reason to start designing by writing documentation is to 

explain the module to yourself. You'll explore your design, find problems, and fill 

in the gaps long before the module is ever examined by anyone else. Later on when 

you return to the module, your documentation will help you remember how your 

module works.

Secondarily, think about the eventual users of the module, but be careful not 

to think only about the short term. In the near future the only user might be 

yourself or the guy in the next cubicle over who knows your brain like the back of 

his eyelids, but that won't last. Software frequently lives longer than you think it 

will. Your module should be designed to stand the test of time make sure it has 

enough documentation to make its own introduction.

Make Your Case

Consider writing some documentation about why the module is being written. 

This may seem brutally obvious, but in many cases it's not. For example, if there is 

an existing CPAN module that provides similar functionality, you should explain 

72