why the perl documents is hard to understand?

Discussion in 'Perl Misc' started by Xiaoshen Li, Nov 7, 2005.

  1. Xiaoshen Li

    Xiaoshen Li Guest

    Hi,

    I am learning Perl now. I have computer science background. One
    important tool for learning a language is to learn how to read its help
    manual. For example, JAVA has all the functions document pages online.
    So any time, if I don't understand a function or need a function for
    doing something, I can check out the document pages. But I found Perl's
    document pages are so hard to read.

    http://search.cpan.org/dist/perl/pod/perlfunc.pod

    I have tried to read the descriptions of some functions. I am so totally
    lost. The wording, the phrases are so hard to follow. I feel I am
    reading an acient scripture.

    Unix/Linux 's man pages are also badly written. But I feel Perl's is
    even worse.
     
    Xiaoshen Li, Nov 7, 2005
    #1
    1. Advertisements

  2. Xiaoshen Li

    Xiaoshen Li Guest

    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.

    This similar trick clearly cannot work in Perl, unless I am at a
    prefessional level already. (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.

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

    Generally, I wish computer science people could improve their expression
    skills dramatically.

    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.
     
    Xiaoshen Li, Nov 7, 2005
    #2
    1. Advertisements

  3. You can also get the documentation for a specific function by typing
    'perldoc -f <funcname>' at the command line; this makes it a good deal
    easier to read only the documentation for the function you're
    considering.
    Please give us an example of a function whose documentation you feel
    is inadequate. We are always trying to improve the state of Perl
    documentation, but if all you tell us is, "It's bad", then we have no
    information that we can actually use to improve things. Instead, what
    we need is, "This documentation is bad, because the way it is written,
    I don't understand if I can do this or that. I think it would be
    easier to understand if you said it this way." Only please be more
    specific than that. :)
    Many of us don't agree, but I think also that even people who feel the
    docs are fine for them would agree that for other people, they can be
    improved. So tell us how they can be made better, and we'll do what
    we can. Sometimes we may simply disagree, but if you read this
    newsgroup for very long, you'll notice that FAQs are posted frequently
    here, and for very many of them, we will have discussions about how to
    improve them which are frequently concluded with a patch.

    So please give us specific examples of what is not good, why you don't
    think it's good, and if possible, how you think we might improve
    what's there. Some discussion will result, and either you will say,
    "Oh, I didn't realize that, you're right, that is the best way to
    explain it," or perhaps we will say, "That is a confusing way to put
    it. How about this way?". Sometimes, we will have to agree to
    disagree. But if you don't give us specific examples, all we can say
    is, "We're sorry you don't like it," and leave it at that.

    -=Eric
     
    Eric Schwartz, Nov 7, 2005
    #3
  4. Xiaoshen Li

    John Bokma Guest

    That's because you are reading a reference manual, not a learning book.
    Yup, if you use them to learn, true. They are reference pages.

    Java class documentation is also very hard to read if you know nothing
    about the language. Of course, since it's a reference, not a tutorial.
     
    John Bokma, Nov 8, 2005
    #4
  5. 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.
    I do not agree; most of how I have learned to program in Perl has been
    reading the online documentation.
    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.
    Nobody here really cares one way or the other.
    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.
    No it is not. Will you help us explain things better, or will you
    only complain and not try to improve Perl documentation?

    -=Eric
     
    Eric Schwartz, Nov 8, 2005
    #5
  6. I am confused as to why you think this analogy is appropriate here? Do
    you expect all Perl programmers the world over to delete all Perl
    documentation on our hard drives and start writing it from scratch?

    You haven't given examples of specific documents that you have
    difficulty with. You haven't pointed out how things can be made better.

    Eric patiently explained why you should do that. You have ignored his
    advice, and trashed your opportunity to actually make things better.

    Instead, we get this drivel about how Unix and Perl docs suck. Tell me,
    what good is that? What purpose does does your complaining serve?

    On second thought, please don't.

    *PLONK*

    Sinan
     
    A. Sinan Unur, Nov 8, 2005
    #6
  7. How awkward! Do you really have to dial up your ISP, start your favourite
    browser, ... just to find out how a Java function works?
    Well, then that is one point where Perl is vastly superior.
    All the Perl documentation is installed as part of Perl on your local system
    and you can easily access it using "perldoc".
    No large browser to start, not dialup to your ISP, just simple, easy, and
    straightforward.
    Never went there once in some 10+ years of on-and-off Perl programming.
    Do you have some concrete example?
    Well, no. They are terse and to the point for experienced people to check
    out details about how a function (command, operator, ...) works. They are
    definitely not meant as tutorial.

    jue
     
    Jürgen Exner, Nov 8, 2005
    #7
  8. Xiaoshen Li

    John Bokma Guest

    Thanks for not top posting.
    Yes, it is a reference. Not a tutorial.
    Because you have next to zero skills in Perl. Yup, the trick doesn't
    work then since first it isn't a trick, and second it's not a tutorial.
    Yup, which is the same as with the man pages, funny eh?
    Again you're wrong. It's a *reference*, which should be checked if in
    doubt. Even professional programmers check the references, just to
    prevent silly things like "defensive" programming (meaning in this case:
    cluttering the code because one is not sure, and guesses what things
    do).
    How does this differ from man pages (the answer is: not).
    True, and a man page is not the right place. Imagine that each and every
    man page would consist of pages and pages of introductionary material,
    so everybody could understand it (if such a thing is already possible, I
    doubt it). This would make each and every man page a big read.
     
    John Bokma, Nov 8, 2005
    #8
  9. Xiaoshen Li

    jack Guest

    What is it about the 'Generals' in this newsgroup.

    Do you really find yourself getting that agitated about the fact that
    the vast majority of posters into this group are relatively new to
    either perl, newsgroups, or the comp.lang.perl.misc newsgroup that you
    feel compelled to berate them about not having read the
    comp.lang.perl.misc guidelines, or not complying to your idealised
    notion of how to communicate within a newsgroup ?

    Haven't you yet got used to the idea that many of the people posting
    into this newgroup are doing so from Google, and don't realise that
    Google doesn't automatically comply with your guidelines ?

    Haven't you yet realised that when so many people take the time to
    complain about certain aspects of perl, be it the use of seemingly
    every conceivable glyph on the keyboard, to the structure of the
    documentation, to the non-standard (perl-specific) regular expressions
    syntax, that this is an indication that not only may there be a
    problem, but that the poster is probably trying to impart some of their
    wisdom, which like it or not, may well be the result of much more
    programming experience than your own.

    I have only begun to use perl in anger after 18 years as a professional
    programmer. That's just about exactly the same length of time that
    perl itself has been in existance. I am sure that perl, and some of
    the comp.lang.perl.misc regulars, have something to teach me - yet I
    am also sure that those same regulars would benefit from some of my
    experience.

    I am sure that posters are grateful for any help they receive, even
    when they don't say so. I know I am grateful.

    I am certain, however, that many of the 'Generals', the regulars who
    are so instructive and generally helpful, could benefit from a little
    less militancy. I honestly don't see the same degree of hostility in
    other newsgroups in which * I * am a 'regular'
     
    jack, Nov 8, 2005
    #9
  10. You don't need to know Perl or Usenet, you just need a minimum of common
    sense to realize that only saying "the docs are bad", without explaining
    in which way that would be the case, is totally pointless.
    Why would using a particular interface to Usenet justify breaking of the
    netiquette? The netiquette is for people to comply with, not for tools.
    What kind of wisdom do you read in statements similar to "the docs are bad"?
     
    Gunnar Hjalmarsson, Nov 8, 2005
    #10
  11. Xiaoshen Li

    Paul Lalli Guest

    I would hope that most beginners find it logical to start with `perldoc
    perl` which contains:
    ====================================
    For ease of access, the Perl manual has been split up into
    several sections:

    perl Perl overview (this section)
    perlfaq Perl frequently asked questions
    perltoc Perl documentation table of contents
    perlbook Perl book information

    perlsyn Perl syntax
    perldata Perl data structures

    <SNIP>

    (If you're intending to read these straight through for the
    first time, the suggested order will tend to reduce the
    number of forward references.)
    ====================================

    Certainly seems like it's pretty explicit about the order in which they
    should be read..

    Paul Lalli
     
    Paul Lalli, Nov 8, 2005
    #11
  12. No, I haven't. And I will never conceed to the idea that Google can take
    over Usenet at their will and lure more and more people to use their web
    interface because a normal person with a normal news reader cannot
    comprehend postings posted via Google Groups any longer.

    There is no reason to abandon 20 years of tried and proven customs unless
    you replace it with something better. Google Groups is not better in any
    aspect.

    jue
     
    Jürgen Exner, Nov 8, 2005
    #12
  13. Xiaoshen Li

    jack Guest

    I disagree, Google Groups is superior - to my mind anyway - in the
    follwing ways. It's a Web Interface and so may be accessed through
    most corporate firewalls which typically block anything except port 80,
    and HTML based content they can recognise. It's easier to search than
    the way most of the newsgroup software I have used in the past works.

    As for a 'normal' person, well, my guess is that the current percentage
    of posting from google groups compares close enough to equitably with
    other news reader software to make it 'normal', so unfortunately you
    will probably just have to get used to it.
     
    jack, Nov 8, 2005
    #13
  14. Also sprach Paul Lalli:
    If that is the proposed order then it's bunkus. Why should the perlfaqs
    be read as second document? It's only useful for those who already know
    a little Perl. And why is perlintro not among the first three manpages
    mentioned?

    The truth is that the various perldocs have not been written with
    any order in mind. They were written in different times by different
    people. No matter in what order you'll read them, there'll be passages
    that refer to material not yet presented. The above suggested order
    speaks about reducing 'forward references'. Howard, it doesn't eliminate
    them.

    Tassilo
     
    Tassilo v. Parseval, Nov 8, 2005
    #14
  15. Xiaoshen Li

    Paul Lalli Guest

    Ah, well that's a different criticism entirely. :) And one that,
    fwiw, I agree with. I was just pointing out that the docs *do* suggest
    an order. Just not a particularly good one, it seems.

    Paul Lalli
     
    Paul Lalli, Nov 8, 2005
    #15
  16. Xiaoshen Li

    Paul Lalli Guest

    There's one key factor you're missing in that statistic: The *vast*
    majority of the "regulars" - the ones who actually *answer* questions,
    as opposed to only ask them - prefer the traditional style of replies
    and do not use Google Groups. If you want a decent chance of getting
    your questions answered, *you* will have to get used to that.

    BTW, this was posted from Google Groups, living proof that it *can* be
    used to post in accordance with the guidelines, and anyone who chooses
    not to is lazy and/or ignorant.

    Paul Lalli
     
    Paul Lalli, Nov 8, 2005
    #16
  17. Xiaoshen Li

    jack Guest

    Again, the inclination to cast aspersions simply cannot be repressed !

    Have a heart, man. A state of ignorance is not *normally* a choice.
    http://en.wiktionary.org/wiki/ignorance

    My guess is than less than half the posters to this newsgroup via
    google realise that their posts are somehow deficient and causing any
    issue amongst the readers. Perhaps your typical diatribes should be
    redirected to the fine folks at Google who provide the interface to
    this group.
     
    jack, Nov 8, 2005
    #17
  18. Xiaoshen Li

    xhoster Guest

    Alas, this increasingly seems not to be the case. Now the man page often
    says little more than to see the "info" page, which are often missing or
    useless.
    I was once a beginner in Perl. I've read the perldoc pages, and understood
    much of it. It is where most of my knowledge comes from. If that doesn't
    work for you, perhaps you should read a book intended to teach beginners,
    rather than reading the documentation.
    I agree. I think computer science people should start doing so by
    providing concrete examples and suggested improvements, rather than just
    vague whining, when they criticise other people's expression skills.
    Xho
     
    xhoster, Nov 8, 2005
    #18
  19. Xiaoshen Li

    axel Guest

    The guidelines are designed for people to be able to help those
    seeking advice. Hence vague descriptions of problems or errors
    raised are usually useless. Rather than repeating this ad infinitum,
    is it not easier to point people to the posting guidelines?
    Er, yes... but by informing people who use Google that it is possible
    to comply with the guidelines, it helps everyone. Otherwise we
    descend into using Google default standards which do not translate
    properly into Usenet standards.
    If the complaints or comments are specific, then yes, they may make
    sense. Vague complaints do not.

    But then there is always the danger that the complainer might just
    be wanting Perl to be more like his previous language experience.

    For example you mention 'every conceivable glyph on the keyboard'
    - perhaps some people find this a problem. But it would be useful
    to know why these people find it a problem.
    You are welcome to contribute your experience.

    Axel
     
    axel, Nov 8, 2005
    #19
  20. Xiaoshen Li

    xhoster Guest

    Considering that this deficiency is pointed out over and over and over
    and over, then lack of comprehension cannot be due to involuntary
    ignorance. It is either willful ignorance or just plain stupidity.

    Xho
     
    xhoster, Nov 8, 2005
    #20
    1. Advertisements

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments (here). After that, you can post your question and our members will help you out.