The question is should the documentation shipped with perl document the features available with that distribution, or should it document the features available

The question is should the documentation shipped with perl document the features available with that distribution, or should it document the features available in the wider Perl culture? For example, Moose has always made an effort to cooperate with the native Perl object system. The documentation in the perldoc's for object oriented programming isn't wrong. The skills you learn from perltoot and companions will transfer to Moose, you'll know how the underlying implementation works. Is this the right way to learn Perl's Object Oriented programming? That is an argument the Perl community itself is having[1]. As that argument is resolved the documentation is updated. If you think about this in startup terms. Moose as a project is 4 years old. Would you invest in a startup that had an exit strategy that was targeted for than than 5 years? Moose has just recently (in the last year or two) reached a dominant market position when compared to the existing competition (Class::MethodMaker, Class::STD, etc) but still is adopted by only 5% of the total market (that is we have ~1K direct downstream dependencies out of about 20K distribution on CPAN). It would be premature to expect the industry to recognize let alone promote Moose as the de-facto standard. However it would be an excellent bet that sometime in the next few years that will happen. Of the "Modern Perl" distributions out there Moose is one of the most consolidated in it's scope. Things like Catalyst have been gaining new competition (Dancer, Mojolicious) in their respective markets. It's interesting to watch things that appear to my untrained eye like market forces play out across the adoption of various CPAN modules. To circle back around, perl documentation needs to strike a careful balance between what they can guarantee exists (bless $ref, __PACKAGE__) and what the community accepts as best practice (use Moose;). The documentation needs to intentionally be less dynamic than the fashions of the community. It must be conservative enough to provide continuity so that someone who happens to be on a perl-5.8.8 box (released 3 months before Moose, and still the standard on RHEL if I recall) doesn't learn a whole different set of "best practice" modules than someone on a 5.10.1 box. It does however need to be updated as things like Moose take over the mind share and prove themselves out. When only 1 in 20 modules you run into will likely involve Moose, you'll still need to understand the native solutions. When that ratio changes, the balance will need to change too. [1]: http://stackoverflow.com/questions/980751/should-i-learn-perl-5-oo-or-moose-first/ http://stackoverflow.com/questions/980751/should-i-learn-per...