develooper Front page | perl.perl5.porters | Postings from November 2003

Re: Poor State of the Man Pages

From:
Adam Turoff
Date:
November 28, 2003 14:23
Subject:
Re: Poor State of the Man Pages
Message ID:
20031128222224.GA3261@panix.com
On Fri, Nov 28, 2003 at 10:31:16PM +0200, Shlomi Fish wrote:
> On Fri, 28 Nov 2003, Randal L. Schwartz wrote:
> > Where is the failure you keep noting?
> 
> I'd like to have a good, free, high-quality reference for Perl, that would
> be suitable for beginners as well as hard-core Perl/UNIX/shell/whatever
> hacker-supreme gurus. Something like Python has at
> http://www.python.org/doc/2.3.2/, PHP has at
> http://www.php.net/manual/en/, etc. Is it too much to ask? Is it too much
> to expect? And if it is, how come you explain that it exists for both
> Python and PHP now, which are two of our biggest competitors?

Shlomi, this is the third or fourth time you've held up the Python and
PHP documentation as an idealized version of what you think the Perl
docs should be.

Both PHP and Python were created with a primary goal of being easy to use
for beginning programmers -- those new to programming, those new to the
language, and those who do not have deep experience with Unix or some
other platform.  Comparing Perl's docs to those of Python and PHP is simply
a red herring.  Perl *NEVER* had a goal of being easy to learn as a first
programming language, or being easy for non-Unix hackers to learn.  Perl
was designed to be easy to *USE*, initially by english-speaking Unix
hackers, and now, sixteen years later, Perl is used by programmers around
the world speaking a variety of different languages, using different
operating systems, with skills ranging from the newbie baby-talk
programmer to the very experienced hacker.

Perl is a power tool designed and used by know what they want to do an
need to do it with a minimum of fuss.  Perl's documentation, printed
books, magazines, websites, mailing lists, conferences, tutorials and 
either (a) cater to that audience or (b) teach the skills necessary to
become part of that audience.  

We're sorry that your friend can't find the information he needs across
the thousands of pages of documentation, gigabytes of web content, or
hundreds of books on the topic.  Quite frankly, it is not our job to
make Perl as easy to learn as possible for the greatest number of people
across the globe, regardless of aptitude, ability to pay, the state of the 
<insert-country-name-here>'s economy, or access to a computer.  

Furthermore, your friend's immediate problem seems to have been solved
already.  He doesn't need to *BUY* Programming Perl, he needs to *READ*
it.  Lending him your copy (gasp!) addresses his immediate needs.
Attacking literally thousands of volunteers telling us, "your docs are
all bad because my friend can't understand them!" doesn't help anyone,
especially you or your friend.

Finally, you have failed to prove that there even *is* a significant gap
in Perl's documentation.  You have succeeded in proving that *you* *think*
there is, based on a handful of data points.  You have also succeeded in
demonstrating that the vast majority of those who are competant enough to
help you disagree with pretty much all of your basic assumptions.

> As time goes by, the younger generations who became introduced to
> computers in an early age, will be less and less willing to bother getting
> hold of a book just to learn how to hack something. For them, learning to
> hack something is a trial-by-error, write-this-write-that,
> consult-this-and-that, google-here-and-there, etc. procedure. I know,
> because I can tell that that's how I learned a great deal of things, and
> still do to a great extent. And Python and PHP give way to these
> kind of people much more than Perl at the moment.

If that's the case, then don't let us stop you.  You don't need our
permission to write better docs that let everyone learn how to program
Perl.  Get started and let us know the results.  If the need is truly as
great as you say it is, your docs will surely be indispensible.

Z.




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