Let’s face it, the man pages (or perl*.pod), which are the definitive resource on the exact behaviour of Perl are very bad. Maybe they were OK for expert Perl 4 or Tcl hackers, or those that knew UNIX shells, sed and awk well. But nowadays we can expect people to come even without knowledge of the DOS or Windows command line, much less UNIX wizardry.

Perl is not and cannot be a “point-and-click-no-think” language. I’m not going to fall into the trap of trying to make it so. Even the lamest GUI kiddie eventually learns to invoke a text editor and write some glue code for whatever he needs to get a web-site or whatever working. Perl is much too powerful, to be something like ASP, where you can write wizards to perform most common tasks. In Perl, you can in one script, write a full application. This is something that while perhaps possible in ASP, it was not intended to do.

Still, the fear of writing code and thinking in terms of variables, functions, objects, modules and other abstractions is not something that for people above a certain age is easy to overcome. Visual Basic for Applications is one of the things I like most in Excel, but most people don’t know it, and most books don’t teach it. Why? Because it involves actual coding and people don’t like that. Ironically, it’s very useful, too.

Now, a documentation should guide a newbie step by step and explains: what is a variable? what is a scalar? what is a number? what is a string? how they convert into each other? What is an array and what it is good for? Same for hash, object, etc. All these things may have different semantics in Perl than in most other languages. And all these things need to be explained clearly and reasonably, without depending on an analogy to tools that are way over Mel’s head at her current position.

I don’t want this knowledge to be hidden from the world in some proprietary O’Reilly books. I did my best to remedy it, and Simon Cozens did even more. I think the reason people think Perl is such a poor language to learn or even for complete beginners, is not because of the syntax and semantics themselves, but because of its poor documentation. That put aside, I think publishers making their books available online, will only help them sell more books (assuming these books are good, of course). Otherwise it’s similar to buying an apartment without seeing it first.