Perl is very well documented: but you may still find it confusing. Odds are, you're just not the intended audience. As the early manual pages stated, perl was written as an alternative for using UNIX shell tools and C, and that was, quite reaonably, the assumed background for the documentaton. The documentation assumed, (and to an extent, still does), that you already understood programming terms and concepts, and just want to try out this new language called perl.

Perl is no longer very "new", and the audience for the documentation is no longer limited to ex-C and shell programmers, but the documentation has remained largely the same. If you want to re-write some of it for a new target audience, I'm sure it would be appreciated. Good documentation is valuable, because documentation is hard. You have to get all the details right, or the newcomers will learn the wrong things.

I learned perl from the online documentation, and very much appreciated it. I was part of the target audience, so that worked well for me. At the time, I thought perl was much better documented than C, which is what I was using. I didn't know where to find a central list of all the C string handling functions that were available on my UNIX system, and I was getting frustrated with trying keyword searches on the word "string". Perl had everything documented on one page.

You might want to try some of the other resources targeted at learning programming in general, or learning perl in specific. Perhaps a copy of the book "Learning Perl" would help, if you find that you learn well from books.

perldoc -f <functioname> brings up help on a built-in perl function.

Good luck, and keep learning!

--
Ytrew Q. Uiop