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

Re: Poor State of the Man Pages

From:
Shlomi Fish
Date:
November 27, 2003 04:44
Subject:
Re: Poor State of the Man Pages
Message ID:
Pine.LNX.4.56.0311271433310.616@vipe.technion.ac.il
On Thu, 27 Nov 2003, Alan Burlison wrote:

> Shlomi Fish wrote:
>
> > 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).
>
> Looks like English to me:
> http://dictionary.reference.com/search?r=2&q=transliterate
>

It is, but what I meant was its meaning deviates from the meaning we mean
by the tr/// operator.

> I'm all in favour of improving documentation, but I would not like to see
> the documents 'dumbed down'.

Actually, at the moment, the documentation is quite cryptic and hard to
understand and people can have problem understanding it even if they
already know the basis of Perl.

So, in a way it should be made more clear and idiot-proof. I don't know
what you mean by "dumbed down" exactly.

> The online manpages are meant primarily as a
> reference for people who already know some perl, not as an introductory text
> - as you have already said there are plenty of good introductory books that
> already cover this ground.
>

Right, _some_ perl. But let's face it: there are many Perl programmers
nowadays who:

1. Are not experienced in any other programming language.

2. Are not native speakers of English.

3. Have little if any experience with UNIX.

4. Just want to find out how to get a job done.

Now other technologies such as PHP or Python have adapted their
documentation to accomodate with people who are any of the following four.
In Perl, the situation is far from being ideal.

Many times it's not enough to say what a feature does in one clause, but
it is also necessary to explain it for people who are less knowledgable
than us, all mighty Perl/UNIX/English/hacking gurus. My friend is one
example, and I believe many people are considerably worse than him.

Do we agree?

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



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