Not terribly difficult, but I sure wish that code fragment had been added to the README.

That sums the problem up in a nutshell. Often the response from authors is something along the lines of: "I've been so busy with the code that I haven't time to do 'documentation'".

But most times we aren't asking for, and don't need, reams and reams of heavily structured and typeset words; just a simple piece of code that the authors of these modules can write in a few minutes, from memory.

10 or 20 lines of code that a) compiles clean; b) runs; c) does something simple but correct.

And that isn't hard for the author(s) of packages to write; but without it, it can be days (or weeks; or never) for the new user to work out.

Authors: Eshew the 'bloody great big list of repetitively formatted apis; ditch the diatribes of personal/professional/project philosophies; don't bother with fancy graphics, cute mascots, pretty logos; don't refer me to files buried in tarballs; and don't bore me with adverts, hyperbole and marketing spiel; GIVE ME SOME CODE!

A small, complete, correct, (standalone), working example that does something simple, but vaguely realistic and useful.

After that, I can try things, read the errors, make changes, see what happens, and if I get really stuck, come back to you (or a forum) with a specific question that probably won't take anyone familiar with module more than a few seconds to answer.

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^2: The problem of documenting complex modules. 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.