Thanks to everyone who took the time to contribute.

The consensus, such as it is, it that the synopsis should contain a short, clear, complete & correct sample usage, that acts as a working starting point on which to build.

The other idea that (for me) stood out was toolic's suggestion that there could be a Tiny/Simple version of the package that acts as an 'easy in' for the full blown all-singing & dancing version.

Beyond that; the only conclusion I can draw is that good documentation is hard, and not fun, and programmer's are apt to get away with the bare minimum. And often less than that.

My own personal view, unsupported by anyone else who contributed here, is that too much documentation is both a real and prevalent factor; and that automated documentation al la doxygen, javadoc etc. is almost worse than none; as it gives the appearance of 'well documented' with none of the true benefits.

Volume does not equate to good; and comprehensive is perfect for Reference; but it needs a Guide to make it usable.

With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday'
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.
I'm with torvalds on this Agile (and TDD) debunked I told'em LLVM was the way to go. But did they listen!

In reply to Re: The problem of documenting complex modules.(Summation.) by BrowserUk
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.