Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??

Well, at least you understand the nature of the problem, which in my experience means you're 80% of the way to a solution. :-)

Many CPAN modules are quite poorly documented (and I'm including my own here). They often do a good job of listing the functions/methods defined by the module, with a brief description of what each function does, its inputs, its output, etc (we mostly have Test::Pod::Coverage to thank for that; without its existence CPAN documentation would be a lot worse); and they're usually quite good for boilerplate sections such as "here is the link to report bugs".

The places they fall down is documenting why you might want to use the module in the first place (I suppose the assumption is that if you're reading the documentation, you've already made that decision); and fully worked practical examples of the use of the module, especially showing how it interacts with other commonly used modules. (For example, JSON could document how to interact with JSON RESTful APIs over the web using LWP::UserAgent; or how to manage collections of JSON on the file system using Path::Class.)

There are fairly obvious reasons for this. If you're writing a module because you just need to get a job done, then you're probably concentrating more on doing the job than documenting it. Or if you're writing a module for fun; then documenting it is likely to be the least fun part. (And of course there are plenty of people for whom English is not their primary language, who find writing documentation in English especially difficult.)

One overlooked area of documentation is the project's test files. These are Perl scripts (but with a ".t" suffix instead of ".pl") which show the software's intended behaviour. Invest some time in learning how Test::More works, and it will pay dividends - you'll be able to dive into a module's test cases and use them as extra documentation!

If you do have any ideas for documentation for a CPAN module, submit it (in pod format) to the project's bug tracker. In most cases the author will be very happy to accept it - documentation provided this way is documentation he/she does not need to write himself/herself! Especially that sort of documentation about how and why to use a module in real-life tasks, which is so often overlooked. In cases of very extensive documentation, maybe format it into a separate document from the main module documentation. (e.g. for module Foo::Bar, write a Foo::Bar::Cookbook, Foo::Bar::Tutorial or Foo::Bar::FAQ document.)

There ought to perhaps be a project that looks at the top 100 most important (by whatever metric) distributions on CPAN; identifies what they are missing in documentation; and writes it! That is, we should do for documentation, what Phalanx already did for test suites.

Update: I've expanded upon this post in perldoc plus plus.

perl -E'sub Monkey::do{say$_,for@_,do{($monkey=[caller(0)]->[3])=~s{::}{ }and$monkey}}"Monkey say"->Monkey::do'

In reply to Re^3: How to read CPAN documentation by tobyink
in thread How to read CPAN documentation by perl.j

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others having a coffee break in the Monastery: (4)
As of 2024-03-29 09:40 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found