jeffa says > Documentation is not required to be easy to understand, just accurate and up to date.

I'm not sure I agree with this entirely. I would s/not required to be/not necessarily/ and agree. But documentation should strive to be easy to understand. That is its purpose. It should be either easy to understand by being organized in a fashion that facilitates rapid reference (if it's reference documentation) or it should be written in a way that fosters comprehension of a new concept (if it's tutorial documentation). (And thanks by the way for the link to Barnes & Noble's listing of Learning Perl. Did anyone else notice that people who bought this book also bought other Perl books only from O'Reilly as well? It's like no other publisher really can find the mark on this.)

I think the point you are making is that reference documentation should be somewhat terse so that an experienced reader can easily get to the salient facts without having to wade through a lot of elementary explanations of terms and so forth. (Sorry about this message. I couldn't find my "so called LASER BEAM" when I went to write it. So it's tutorial documentation style rather than reference documentation style.) But being terse doesn't necessarily forbid being easy to understand.

I think that in the Perl world, because we are so compulsive about writing the smallest number of instructions to get a job done, we try to take the same approach with writing and communicating. It doesn't always work out. And while the effect is not limited at all to the Perl world, there are many fine instances in the Perl documentation of Obfuscated Technical Documentation at the highest form of the art.

That's what makes Perl Monks more valuable to me than the documentation or any of the existing books about Perl. The things that have been written in conjunction with the understanding that is demonstrated here out of the minds of the community members makes something that really leads me to enlightenment.

...All the world looks like -well- all the world, when your hammer is Perl.
---v

In reply to Re: (jeffa) Re: array pushing by agentv
in thread array pushing by sulfericacid

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.