I'm probably as much a "CPAN programmer" as Perl programmer, since there's so much stuff out there that's already done that helps me solve my problems.

The single most valuable thing to me in module documentation is a few little snippets of working code that I can paste in and run as a starting point. It removes ambiguity over what really needs to be done in setup and what needs to be passed where. Ideally for a complex module there will be a few examples that address likely use cases of people coming to the module for the first time. They don't have to be complicated, but if they address in a few lines what I might have spent a bunch of time trying to sort through without the module, then they a) show me that the module can address my problem, and b) give me an entry point where I can start building my bigger solution without having to spend a bunch of time just trying to get started.

In reply to Re: The problem of documenting complex modules. by bitingduck
in thread The problem of documenting complex modules. by BrowserUk

Title:
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, details, 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, summary, 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.