Removing Hostility from User Documentation


If I didn't have better things to do with my time, I'd write new documentation demonstrating how to write your own XML parser and propose its addition to the Perl 5 core documentation as pod/perlxml.pod. Sure, you shouldn't parse XML with regular expressions, but as Perl 5 doesn't include an XML parser and people want to parse XML with Perl 5, why not show them one awkward, fragile, and ill-advised way to do things without recommending to, as the world's most effective and capable Perl 5 programmers do, install a real XML parser from the CPAN.

(See also the debate over a proposal to revise the assemble-it-yourself, aren't-you-so-clever documentation for the minimal default Perl 5 object system borrowed wholeheartedly from Python. The mind boggles at the reticence to make things easier for novices and more consistent and clearer for the rest of us.)


The documents that ship with core should describe how to do thing with the core and point to better ways. I don't think he falls far short in achieving that. Maybe removing the Moose examples and just have a section at the end stating while you can do OO "that way", "this way" is better and list Moose, Mouse, Object::Tiny and explain what makes them better options.

The only reason to write an object system by hand in Perl 5 in 2011 is because you can't install something better from the CPAN. What's the likelihood that anyone running Perl 5.14 in the next couple of years (assuming such a feature even makes it into Perl 5.14) won't be able to install something better from the CPAN?

I think it's important to begin making a stronger distinction between tutorials and references.

Obviously we don't want Moose talked about in 'perlobj', or other CPAN code talked about in function documents, etc.
Tutorials, though, have an entirely different purpose. They are meant to walk a newcomer through the steps necessary to begin writing useful relevant code.

Unless our goal is for new Perl developers to join our ranks writing 1997-era code so we might pat ourselves on the back as we tell them to disregard all the gory details they read in the perldoc tutorials... we, as a community MUST morph these tutorials to teach Perl newcomers whatever is critical to know on that given topic.

We need to collectively ditch the "Perl core only" mentality, and embrace the CPAN in our tutorials.

Developers who have access to CPAN for their software FAR outweigh those who do not. It seems backwards to argue that the few without CPAN access will be inconvenienced by initially learning the CPAN way. In our status quo with today's tutorials, those looking to write community-accepted modern code have to go out of their way to learn how to do so.

If we have to do one group a disservice, shouldn't it be the few rather than the many?

Modern Perl: The Book

cover image for Modern Perl: the book

The best Perl Programmers read Modern Perl: The Book.

sponsored by the How to Make a Smoothie guide



About this Entry

This page contains a single entry by chromatic published on March 1, 2011 9:26 AM.

Rock Paper Scissors Butterfly Velociraptor was the previous entry in this blog.

Why Modern Perl Teaches OO with Moose 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?