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

Re: Poor State of the Man Pages

From:
Dave Rolsky
Date:
November 27, 2003 13:55
Subject:
Re: Poor State of the Man Pages
Message ID:
Pine.LNX.4.58.0311271544421.29731@urth.org
On Thu, 27 Nov 2003, Shlomi Fish wrote:

> 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.

Hmm, I've found the qmail docs pretty horrid, far inferior to Perl's.  But
that's comparing apples to oranges.  Most of the things you list are apps
(qmail, make, postgres, etc.) and have a much narrower scope than Perl,
and as such are much easier to learn through online docs.  Of course, if
you've never used SQL before at all, good luck learning to use MySQL or
Postgres from their online docs.

I haven't looked too much at the Ruby, Python or PHP online docs.  My
impression from the PHP docs I've looked at online was that it was mostly
reference material with user-supplied annotations, and I wasn't hugely
impressed with it, but I've not delved into it in an attempt to learn the
language, so there's probably bits I've missed.

For Ruby, it looks like the Programming Ruby book is available online
under the Open Publication License, a great choice I strongly support (see
masonbook.com), but that's hardly the same as the core Ruby docs.

If that book weren't available online, would someone write the equivalent
for the Ruby docs?  I doubt it.  They'd tell people to go read the book.

> 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.

I generally like to read a book (or books) first, and then use online
resources as references.  I have no problem with buying the "deprecated,
inferior" form of documentation.

> 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.
>
> > 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?

No.


-dave

/*=======================
House Absolute Consulting
www.houseabsolute.com
=======================*/



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