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