Front page | perl.perl5.porters |
Postings from November 2003
Re: Poor State of the Man Pages
From:
Shlomi Fish
Date:
November 28, 2003 12:31
Subject:
Re: Poor State of the Man Pages
Message ID:
Pine.LNX.4.56.0311282138220.14846@vipe.technion.ac.il
On Fri, 28 Nov 2003, Randal L. Schwartz wrote:
> >>>>> "Shlomi" == Shlomi Fish <shlomif@vipe.technion.ac.il> writes:
>
> Shlomi> My point is that the perl*.pod pages should be suitable for a
> Shlomi> large part of our demographic.
>
> AND THEY ARE!
>
> You really don't know of what you speak.
>
> The core audience of Perl is programmers and sysadmins who know Unix
> and have smatterings of other languages under their belt, like C, and
> because of Perl's origin, are also fluent in English.
>
My friend:
1. Knows C well enough. (at least the language itself)
2. Is fully fluent in English.
3. Has a little (but not a lot of) background in UNIX.
And still found the man pages (at least those that ship with RedHat 9.0)
hard to understand.
By demographic I also mean the demographic of people who are relatively
new to Perl, not just or even more so than the people who are already
fluent with it.
> Please read my other posting on this.
>
I read it again now. I do not agree with it completely.
> You just don't get it, do you?
>
> Shlomi> Of course, all of this would have been much easier if
> Shlomi> "Programming Perl" was available online for free.
>
> Frankly, other than some editing, there's not a heckuva lot that's in
> Programming Perl now that isn't already online. In fact, there
> are clearly more tutorials and quickstarts in perl*.pod than there
> is in Programming Perl now!
>
Probably, but as a concentrated _reference_, Programming Perl beats the
hell out of the core (non *tut) man pages. And the perl*.pod documents are
considered the core reference documentation to Perl.
> Shlomi> There are already some replacements for "Learning Perl" (like
> Shlomi> Simon Cozens' book) online.
>
> Why must *everything* be free?
>
I'm not saying it should. The way I see it, putting "Learning Perl" online
now would be redundant. There are already good replacements for it
available online.
> Maybe you don't realize that even with the wonderful sales of the
> books I've been involved in, the return has never been greater than a
> bit better than minimum wage when you count the hundreds of hours that
> go in to making a quality book.
>
Very well. So, you agree that there is more about writing a book than
getting payed for it? And I'm not sure that putting the Camel book online
would harm its sales one bit. For example, if I were an employer, I would
make sure my company bought a copy of it (and other good books) to
circulate between the employees. (and I would recommend my own employer to
do so as well). If or if not it is available online.
> Shlomi - you disrespect the very people that you want to entice into
> a different behavior.
>
I do not.
> The core docs (free!) meet the needs of the core audience. When
> that's not enough, online communities fill in the gaps. When there's
> a market demand for more than that, commercial entities have stepped
> in to help.
>
> 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?
Yet, even as I tried to revamp the existing documentation and make it
idiot-proof (without reducing its usability for experts), I keep getting
feedback as "No! Let's keep it as guru-centric as it is!". I believe the
perl*.pod pages have outgrown their purpose as common UNIX "man pages" and
have become the primum reference for Perl. As such, they should be made
more suitable for people who are less knowledgable then the average
_current_ Perl programmer, or else we'll hear people saying: "I thought
about studying Perl, but heard it has an awful documentation and so
learned PHP/Python/whatever instead." or "I tried learning Perl, but could
not make heads nor tails of its man pages so I switched to
PHP/Python/whatever".
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.
I think this all makes sense.
Regards,
Shlomi Fish
----------------------------------------------------------------------
Shlomi Fish shlomif@vipe.technion.ac.il
Home Page: http://t2.technion.ac.il/~shlomif/
An apple a day will keep a doctor away. Two apples a day will keep two
doctors away.
Falk Fish