Front page | perl.perl5.porters |
Postings from February 2011
> > a tutorial is not a reference. > Indeed, they serve different purposes/audiences/needs. > > Now I'll just put on my asbestos suit. > Good idea. Ciao Richard -- Richard Foley Ciao - shorter than AufWiederSehen! http://www.rfi.net/books.html > 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 > > /*============================================================ > http://VegGuide.org http://blog.urth.org > Your guide to all that's veg House Absolute(ly Pointless) > ============================================================*/Thread Previous | Thread Next