Q: which modules have stellar documentation?

I'm starting some work on a new Perl module and I want to make sure,
from the start, that the documentation is good. Do you have a favorite
module whose docs are particularly well written and well organized?

Of the modules I've encountered, CGI::FormBuilder has the best
documentation. Are there any others I should examine?

Thanks,
Michael

Re: Q: which modules have stellar documentation?

Michael Hendricks wrote:
> I'm starting some work on a new Perl module and I want to make sure,
> from the start, that the documentation is good. Do you have a favorite
> module whose docs are particularly well written and well organized?
>
> Of the modules I've encountered, CGI::FormBuilder has the best
> documentation. Are there any others I should examine?
>
That module does appear to have good documentation. It certainly has *a
lot* of it (44 pages if printed out as HTML), but it should, as it has
many methods. I can appreciate that, as some of my own modules (e.g.,
List::Compare) have voluminous documentation.

OTOH, there are modules I use *frequently* and whose docs I consult
frequently, particularly from the command-line. Most frequently:
Test::More. In those cases, what matters is not so much the overall
quantity of documentation as how much of the essentials of the module
are represented in the SYNOPSIS and are quickly accessible thru 'perldoc
Some::Module'.

Consider this approach: Write your documentation first! That entails
specifying the module's functionality and interface. Show that to
another hacker and ask if it's clear. If not, then you need to revise.
If it is clear, then you can go on to write your tests and, finally,
the code.

jimk

Re: Q: which modules have stellar documentation?

You could check out the things in Astro::* :)

The Test::Pod and Test::Pod::Coverage can help you, too.

--
brian d foy, bdfoy@cpan.org
Subscribe to The Perl Review: http://www.theperlreview.com