Front page | perl.perl5.porters |
Postings from November 2003
Re: Poor State of the Man Pages
From:
Shlomi Fish
Date:
November 28, 2003 03:10
Subject:
Re: Poor State of the Man Pages
Message ID:
Pine.LNX.4.56.0311281302540.4392@vipe.technion.ac.il
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
> 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.
>
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.
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