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

Comment on

( #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

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

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

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

    How do I use this? | Other CB clients
    Other Users?
    Others browsing the Monastery: (6)
    As of 2018-10-19 07:20 GMT
    Find Nodes?
      Voting Booth?
      When I need money for a bigger acquisition, I usually ...

      Results (106 votes). Check out past polls.