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

Re: Revising Perl's OO docs - a new OO tutorial (not a reference)

Thread Previous | Thread Next
Richard Foley
February 28, 2011 23:25
Re: Revising Perl's OO docs - a new OO tutorial (not a reference)
Message ID:
> > a tutorial is not a reference.
Indeed, they serve different purposes/audiences/needs.

> > Now I'll just put on my asbestos suit.
Good idea.


Richard Foley
Ciao - shorter than AufWiederSehen!

> 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
> faqs.
> 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.
> -dave
> /*============================================================
> 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