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
Mark A. Stratman
March 4, 2011 13:17
Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a new OO tutorial)
Message ID:

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

> On Fri, 4 Mar 2011 18:02:54 +0100, Abigail <> 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 Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About