Front page | perl.perl5.porters |
Postings from November 2003
Re: Poor State of the Man Pages
From:
Abigail
Date:
November 27, 2003 16:12
Subject:
Re: Poor State of the Man Pages
Message ID:
20031128001222.GB22083@abigail.nl
On Thu, Nov 27, 2003 at 10:35:23PM +0200, Shlomi Fish wrote:
> On Thu, 27 Nov 2003, Dave Rolsky wrote:
>
> > Buying Perl books supports the authors (like Larry, Randall, and many
> > others on this list) who've contributed to Perl. Complaining that
> > learning something requires buying a couple books is ridiculous. There
> > are not many things in this world worth learning that can be easily
> > learned with absolutely no investment of money.
>
> Actually, as far as computer technologies are concerned, the opposite is
> true. If you can't learn a computer technology from online resources
> alone, then there's something very fishy about it.
> Take a look at Python, PHP, MySQL, PostgreSQL, GNU make, GNU awk, qmail,
> Ruby and the list go on. They all have very adequate documentation online
> for beginners, as well as reference material that is very accessible.
You must have a totally different view of valuable documentation than I
have. One reason I'm not as proficient with Python as I like to be is it's
utter lack of documentation:
$ man python | wc -l
Reformatting python(1), please wait...
270
$ man python | grep 'SEE ALSO'
Reformatting python(1), please wait...
$
MySQL doesn't even come with a manual page, just one large HTML file,
which lacks too much vital information IMO. GNU make uses a twisty
little maze of info files, where it's very hard to find what you want.
If I have to pick only one thing why I think Perl is superiour to other
languages, my pick will be "the documentation that comes with it".
> Generally, the developers of a technology must make sure it is adequately
> documented in an accessible online format if they actually want people to
> learn it. Paperback books are a deprecated, inferior form of
> documentation. When I'm hacking at something I usually don't consult a
> book I have for reference. It is simply too inconvenient. Likewise, I
> learned many things from online resources alone.
>
> If you tell someone that he needs paperware as a reference for a
> technology or as a way to learn it, then it means that someone did not
> give enough time to make sure it is adequately documented as is.
That's quite an insult to the people who have spend countless unpaid
hours to make the documentation what it is.
> > But $40 is a pretty small
> > investment, I'd say.
>
> Are you willing to make a check for the name of my friend to cover the
> expenses of buying the book? Or order it from him in Amazon?
$40 won't let you hire someone long enough to write 1 page of
documentation. People have invested enormous amounts of time,
inconvenience and money to make Perl and the documentation what it is,
and now you are whining that that hasn't been enough, because you have
a friend who doesn't want to invest $40 in his future.
That pisses me off.
Abigail