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

Re: Poor State of the Man Pages

Shlomi Fish
November 28, 2003 03:10
Re: Poor State of the Man Pages
Message ID:
On Thu, 27 Nov 2003, Dave Rolsky wrote:

> 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 learned SQL from the MS Access online help. Can't tell about MySQL or
Post because I already knew SQL when I was introduced to them.

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

Yes, but PHP has some very good tutorials online (one I believe to be part
of the core documentation), which you can easily learn from them. And I
was talking about _reference material_, not introducory material. I think
the Perl 5 reference material (perl*.pod) is lacking in several respects.

> For Ruby, it looks like the Programming Ruby book is available online
> under the Open Publication License, a great choice I strongly support (see
>, 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.

Well, there are many people out there. Some of whom, would rather point
their browsers at the documentation, or just invoke a few commands on
their computer. We should cater for every demographic.

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

"But $40 is a pretty small investment"... ;-)

Never mind, we are getting way off-topic here. I'll go on setting up the
Podlanx project, and start collecting user stories.


	Shlomi Fish

Shlomi Fish
Home Page:

An apple a day will keep a doctor away. Two apples a day will keep two
doctors away.

	Falk Fish Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About