Q: which modules have stellar documentation?

Do you have a question? Post it now! No Registration Necessary.  Now with pictures!

Threaded View

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?


Re: Q: which modules have stellar documentation?

Michael Hendricks wrote:
Quoted text here. Click to load it
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

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.


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

Site Timeline