I use perldoc all the time (the command-line version). I don't know how to be a productive Perl programmer without perldoc -f or perldoc Module::Name. Nor would I try.
One of Perl 5's selling points is that includes copious documentation of the core language and common tasks. If you've skim perldoc perltoc once in a while, you'll find documentation you really ought to read as well as documentation you will wish you had read previously.
Then you'll come across something like perlobj which,
bless its little heart, really isn't that helpful anymore. It
gives far too many implementation details along with helpful-sounding but
ultimately unpleasant advice. (Explaining how to use indirect method
invocation before warning not to use it in the final paragraph of the section?
A lengthy discussion of garbage collection? A comaprison of Perl 5's default
OO with C++? Code examples which show how to bypass method dispatch altogether
as a didactic technique on how method dispatch works?)
That's not the worst file in the documentation.
Writing documentation is difficult. Writing good documentation is very difficult. Editing existing documentation is thankless and fragile and prone to arguments: someone invested hours in writing that documentation a decade ago. We should celebrate that work and offer our most sincere gratitude to everyone who's helped create the voluminous Perl documentation. Even so, when documentation has grown a layer of mold (or when our understanding of the best way to do things has changed), we need to do users the favor of giving them the best advice we have.
Sadly, we'll never see Programming Perl 4E, but we can work to improve the core documentation in terms of advice, accuracy, organization, and completeness. (Even a prominent link to the TPF Perl 5 wiki for "Object Best Practices" in the documentation could keep it relevant in seven years when so-called enterprise distributions begin to ship a Modern Perl, but that's a far different need.)
