Xiaoshen Li said:
Thank you very much for the replies. Yes, a coin has two sides, I agree.
Anyway, I was taught that there is a trick to learn unix/linux. That is
to learn how to read man page. Because the man page is always there to
help you, anytime, anywhere.
I think man pages are useful to remind you how to do something, but
quite often, unless you already know, and want to remind yourself,
more documentation is needed.
This similar trick clearly cannot work in Perl, unless I am at a
prefessional level already.
I do not agree; most of how I have learned to program in Perl has been
reading the online documentation.
(If a person is at that level, I think those
document pages may not be very useful already, at least its usefulness
has been dramatically decreased.) I wish the wording, discriptions of
each function are writen for general people, not for professionals or
the writer himself to read.
Please tell us what, specifically, you have a problem with. All you
are saying now is, "I find Perl documentation hard to read". But if
you do not tell us WHY it is hard for you, and HOW it might be
improved, we cannot change anything. Let us pretend that I believe
that the wording and descriptions of each function is already written
for general people. (That is not the case, but let us pretend it is.)
Now, you must convince me that I am wrong, and you are right. Please
give me one specific function whose documentation you believe is not
written for general people. Tell me why you believe that function's
documentation is not written for general people, and if you can, tell
us how you would change it to be more easily understood. Do not tell
us, "Oh, they're so confusing and difficult to understand", tell me
WHAT is confusing, and WHY it is difficult to understand.
(By the way, the comment "Unfortunately, Linux/Unix man pages are badly
writen." is not from me, is from the book "Think Unix" by Jon Lasser and
I assume & believe a lot of people feel same way.)
Nobody here really cares one way or the other.
Generally, I wish computer science people could improve their expression
skills dramatically.
That's probably true. But it doesn't help us here. We are practical
people-- if someone comes to us and says, "Perl documentation is
hard", we cannot change anything. If that person continues to say the
same thing, then we will eventually decide that person does not want
to make things better, but only complains, and we will stop listening,
and nothing will change.
If, however, someone says, "This document is confusing, because I
don't understand what this means. Please explain it." and then writes
a better explanation, then we are happy to help, and the documents
will improve for everyone.
Now I recall one of the greatest poet in China Tang Dynasty, BaiJuYi.
After finishing a poem, he always read to some old aged general people.
If they don't understand, he always tore it away and restart to write.
It is not easy to explain something.
No it is not. Will you help us explain things better, or will you
only complain and not try to improve Perl documentation?
-=Eric