The biggest complaint I've heard over the years is that the documentation is hard to search. Almost everything is documented, but it's not always easy to find - and sometimes it feels things are documented in illogical places. Scoping for instances, with many details about my() and local() is documented in "perlsub" - which is about subroutines (and this unfortunate marriage of scoping and subroutines has been carried into too many Perl learning books).

Furthermore, those who have written significant portions of the documentation have always shied away from copying sections into other relevant PODs. Which means there are a lot of cross-references. Unfortunally, there are even more cross-references missing. There is *no* index at all, unless you count the list of manual pages from 'man perl'. But that list is incomplete - it only lists the PODs from the /pod/ subdirectory, not the POD that comes with the core modules. Crossreferencing from the core PODs into the core module PODs is almost non-existing.

The documentation is overwhelming. At the same moment, it's often terse, and sometimes requires UNIX and/or C knowledge.

But it's easy to critisize. Many have done so. Not so many have actually tried to fix the situation. Noone has actually managed to write better documentation.

If I were to fix something, I'd first create an index, and the framework to keep the index up to date. BTW, I strongly disagree with the suggested directory structure in the piece you quote. Either you subdivide the documentation on topics, or you subdivide them on their presentation. But you don't put both subdivisions on the same level. Where would I go looking for a tutorial about internals? In the "Tutorials" directory, or in the "Internals" directory?