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

Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a newOO tutorial)

Thread Previous | Thread Next
From:
Dave Rolsky
Date:
March 4, 2011 08:57
Subject:
Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a newOO tutorial)
Message ID:
alpine.DEB.2.00.1103041053230.2213@urth.org
On Thu, 3 Mar 2011, brian d foy wrote:

> So, when it comes to OO, what should the new person read? Although Dave
> doesn't go so far as saying that he wants to replace the various
> non-reference pods, I think that's what should happen. Can we collapse
> perltoot, perlboot, perlobj, perlmod, and perlmodlib into fewer

Actually, I _do_ want to replace all the existing tutorials with my new 
one. My plan is to end up with:

   perlootut - my new tutorial
   perlobj - covers OO from the ground up in detail

I agree that a larger view is probably a good idea.

> documents? Do we have to keep a particular document merely because it
> has always been there evne though no one is updating it?

To answer that question, no.

> First, I'd want to organize it:

I generally agree with you. We need a hierarchy. The current flat 
organization is hard to deal with, and the 8.3 naming is really painful, 
made more painful because everything starts with "perl".

> With some changes to Pod::Perldoc, we can support the hierarchy with
> the old names as a deprecation cycle:
>
>     $ perldoc5.16 perlsyn
>     Warning: perlsyn is now syntax, use `perldoc syntax`

Sounds good to me.

I also think we should consider writing the docs assuming they will be 
mostly viewed on the web, especially for new users. Mostly that just means 
really good cross linking, linking to other websites, etc.


-dave

/*============================================================
http://VegGuide.org               http://blog.urth.org
Your guide to all that's veg      House Absolute(ly Pointless)
============================================================*/

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About