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

Poor State of the Man Pages

From:
Shlomi Fish
Date:
November 27, 2003 01:35
Subject:
Poor State of the Man Pages
Message ID:
Pine.LNX.4.56.0311271106250.29160@vipe.technion.ac.il

My friend has recently graduated from the Technion in Electrical
Engineering. He knows English very well, but is short of
practical experience in programming. To remedy this, he decided to install
Linux on his computer, and to learn UNIX and Perl programming thoroughly
in order to become a better hacker.

Now, he learned some Perl by reading my Perl for Perl Newbies notes[1].
However, I only teach there a limited subset of Perl which just aims to
get people started writing their own code. It is not suitable for
programming Perl idiomatically, much less for reading the code of
experienced programmers.

At one point, I suggested the reader that he can now go over the man pages
and should. However, my friend complained that the man pages were hard to
understand, and I can relate to it, as they are certainly not intended for
people with very little background in UNIX.

He's using the Perl that ships with RedHat Linux 9.0. I can instruct him
to install Perl 5.8.2 or bleadperl, if the man pages there are
substantially better.

I recommended him to buy the Camel Book, which is a good read even for
people who are very good programmers. Still, it was a bit pricy for him
(220 NIS or $40). At the moment he is using a pirated version he found on
the Net somewhere. (of the second edition).

For a long time, I complained that the Perl man pages were probably
intended for either experienced Perl 4 programmers or for seasoned UNIX
shell/sed/awk/whatever hackers. But naturally, reality wanted otherwise
and Perl is now being learned by people with very little experience of
either.

Those people could perhaps get started by reading Simon Cozens' "Beginning
Perl" book or whatever, but still need a good reference. This is either
"Programming Perl" or the man pages.

A good idea to revitalize them and adapt them to our needs, would be to
start a Phalanx like project for documentation. Namely, we:

1. Collect user stories on what they did not understand in the
documentation.

2. Assign volunteers to remedy these issues.

3. Assign volunteers to go over sections of the man pages and try to
paraphrase them to make them clear enough.

4. Collectively decide where the man pages could use some re-organization,
and re-organize them.

Once we're through, we release Perl 5.8.3 with all of the changes applied.
(or maybe delay it to Perl 5.10.x due to configuration management issues)

Are you with me? I volunteer to take the initial effort and get this
effort going. One thing that has to be understood is that the man pages
should be clear, explanatory, and organized. We cannot leave
"transliterate" as such because it's a piece of UNIX jargon and not plain
English. (for example).

Regards,

	Shlomi Fish

[1] - http://vipe.technion.ac.il/~shlomif/lecture/Perl/Newbies/



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



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