develooper Front page | perl.perl5.porters | Postings from February 2011

Re: Revising Perl's OO docs - a new OO tutorial

Thread Previous | Thread Next
Dave Rolsky
February 28, 2011 14:22
Re: Revising Perl's OO docs - a new OO tutorial
Message ID:
On Mon, 28 Feb 2011, Bram wrote:

> Who is the 'primary target' of the documentation that is shipped with Perl?
> a) novice users  OR
> b) advanced users  OR
> c) novice users and advanced users

This is a really good question, and I was thinking of starting a separate 
thread on this.

Basically, my answer is all of ...

A) Novice users new to Perl who may or may not be new to programming. For 
them, we have intro-to-language docs (perlsyn, perldata), tutorials, and 

B) Experienced users who need to look something specific up. They're more 
likely to look in the reference docs, use "perldoc -f", etc. They should 
not need to look in the tuturials.

C) Experienced users looking to learn something new. For example, someone 
might know Perl really well but now they want to learn XS, or they want to 
hack on the core. These users are novices _in a particular area_, and they 
still want focused tutorials on these particular areas.

For the record, my new tutorial is squarely aimed at category A.

Some other questions to think about ...

* What kind of background do we expect novices to have? Do they know C? 
Unix? Sed/awk/shell?

The old answer was yes to all of the above, which explains a lot about 
some of the docs. The new answer is _none_ of the above.

* What are our goals for novices?

I think the existing docs have the wrong goal in many cases. The goal of 
existing docs seems to be to impart a full and complete understanding of 
the topic at hand. I think the goal should be to help the reader get up to 
speed on modern Perl 5 as quickly as possible.

> Is it 'correct' to document something in core that is not shipped with core?
> (Moose/Mouse/... are not shipped with core last time I checked)

Yes, why not? One of the great things about Perl is CPAN. Should we 
pretend it doesn't exist?

I think the best path for a novice to quickly (and safely) write Perl OO 
code is to use an object system off CPAN.

> What with the low level stuff of perltoot/perltooc/perlboot?

When these docs were written, it made sense for a tutorial to cover the 
gory details. My best guess is that their primary audience was existing 
Perl 4 developers.

> You're saying beginning users may not need them and/or might become confused 
> about them but what about advanced users that do understand (and/or need) the 
> information? Is all the information still available in other pods?

That's what perlobj is for. We should have a good from-the-ground-level-up 
reference on Perl OO, but a tutorial is not a reference.


Your guide to all that's veg      House Absolute(ly Pointless)

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About