Front page | perl.perl5.porters |
Postings from February 2011
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