"...they don't have a simple in; a clearly defined and obvious starting point that gives a universal starting point on which the new user can build."

This is nothing but the truth.

It seems like there is a tendency on CPAN that the documentation of some modules is written in a disastrous style. Just good for some initiated who know what to do.

But compared to the documentation of less or more complex modules/classes in other languages, especially a certain language i think that we still live in the Garden of Eden.

I don't know if you program in Java (unfortunately i'm forced to do it now). If not please try to figure out some stuff in this language. A very special experience. I guess you will land on some websites that just show that crap from javadoc. Next step: go to Oracle's Java Tutorial Site. Then go to Stackoverflow and continue. Now buy a book. Steps are interchangeable. No JavaMonks. That was it. I wish you well ;-)

Best regards, Karl

P.S.: IMHO another example of good documentation of complex stuff at MCE by marioroy.

«The Crux of the Biscuit is the Apostrophe»

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