I'm less concerned with some new protocol or format or something than just better docs. But that was my idealized example.

As for the nefarious purpose argument, I look at that as a future use thing. I want better docs so most users get their foot in the door, not so experienced hackers bend the module to their will. Get people using the module, then they'll try to worry about how to enhance it in the future.

Most of the good use cases up front, something that can be cut 'n pasted, and that'll take care of most things. By all means include the docs to hack it like crazy afterwards, but most docs seem to skew towards that at the expense of the n00bs.

In reply to Re^2: Our documentation sucks by jimt
in thread Our documentation sucks by jimt

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.