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

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

Thread Previous | Thread Next
From:
Mark A. Stratman
Date:
March 4, 2011 13:17
Subject:
Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a new OO tutorial)
Message ID:
17A46A67-E941-49EC-B6E9-93879527D323@gmail.com

On Mar 4, 2011, at 11:44 AM, H.Merijn Brand wrote:

> On Fri, 4 Mar 2011 18:02:54 +0100, Abigail <abigail@abigail.be> wrote:
> 
>> On Fri, Mar 04, 2011 at 10:56:37AM -0600, Dave Rolsky wrote:
>>> 
>>> I also think we should consider writing the docs assuming they will be  
>>> mostly viewed on the web,
>> 
>> Personally, I find that an almost alien thought.
>> 
>> Why would anyone use a web interface for something that's already
>> there locally?
> 
> I almost NEVER use HTML presenters for perldoc. I use "man" 95% of the
> time and 4% the quick ref guide and 1% the books.
> 
> So viewing from the web is a no-op for me.


I believe it is important that we begin making a stronger distinction between tutorials and reference materials.

I'm willing to speculate that nearly ALL people reading tutorials are doing so on the web.  Of course *you* folks might not read Perl tutorials on the web, but *you* are hardly the audience of a tutorial.

I'm probably taking this a step further than Dave was getting at.... But there are a lot of great things HTML brings us that POD is incapable of.  And these sorts of things are extremely useful teaching tools in tutorials:
* Images
* Lists
* Tables
* Videos
* etc

To say that we should disregard critical, modern communication tools when teaching Perl newcomers, simply because Unix hackers would be inconvenienced should they ever decide to read a tutorial on their commandline tool of choice is.... absurd.

I certainly concede that reference materials should be be easily viewable on a standalone machine, and should lose no critical content when looked at with 'man' or 'perldoc' on the terminal.  These are the everyday go-to documents we quickly pull up whenever necessary.

A tutorial on the other hand is typically read once.  And I think this line of reasoning applies similarly in deciding whether to use CPAN examples to teach a Perl concept.  The goal of a tutorial should not be to teach a newcomer to work within the constraints of core perl, but instead to teach them how we (most often) *actually* work with the language. 


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