A Perldoc Pruning

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.)

Modern Perl: The Book

cover image for Modern Perl: the book

The best Perl Programmers read Modern Perl: The Book.

affiliated with Modern Perl Whitepapers



About this Entry

This page contains a single entry by chromatic published on September 8, 2010 9:34 AM.

Essential Philosophy for Perl 5 Novices was the previous entry in this blog.

When "Enterprise" is a Synonym for Useless is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.

Powered by the Perl programming language

what is programming?