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






footer




 

 

 

 

 Home | About Us | Network | Services | Support | FAQ | Control Panel | Order Online | Sitemap | Contact

web hosting perl

 

Our partners: PHP: Hypertext Preprocessor Best Web Hosting Java Web Hosting Inexpensive Web Hosting  Jsp Web Hosting

Cheapest Web Hosting Jsp Hosting Cheap Hosting

Visionwebhosting.net Business web hosting division of Web Design Plus. All rights reserved