I came across the node: The sad state of Perl documentation (after reading Why can't mod_perl+Mason just work?). Since it was about 4 years old, I'd like to bring that topic up again. Some of the posts in that thread need updating, for example, the "perl documentation project" doesn't seem to be active anymore(am I right? google didn't return much)

In comparison with other recent programming languages, perl has the best set of books. I have a good collection of the O'Reilly set on my book shelf, the mere glancing of their standing there literally gives me warm feelings, I think it's probably physically healthy to posess those books:-) And no other language has a community as great as that of PM.

Recently, I've been looking into python. I'd say that although their books are of far less quality, their documentation/examples for the novice are superior. One example is the wxPython demo that shows how to build GUI with wxPython, it's written as an application (in wxPython), where the gui examples are listed in a tree node, and for each, one can click on "code", "demo" and "overview" tag to see the source, the result of running that code, and the documentation, respectively. Imagine we have such a demo tool for perl/Tk! Another example is the documentation that came with a standard installation of python, it is in one place, categorizes the modules according to their usage, searchable and indexed. Although ActivePerl came with a better presented documentation, it's still less thoughtful than that of python, and that of the perl books, IMHO.

Now the goal of this post is not to complain, so please spare me the flames. I meant to ask, is there something we, as a community, can/should do to ease the pain of the beginners, actually also those of us less talented veterans. I truely believe all documentation is already there, it's just their organization, or lack of, that makes it less helpful. This is sort of like the web before google.

Replies are listed 'Best First'.
Re: Perl documentation
by PodMaster (Abbot) on Aug 12, 2004 at 22:37 UTC
    Imagine we have such a demo tool for perl/Tk!
    Are you saying there isn't one? Because there is you know, its called widget. Also, wxPerl has a pretty similar demo.

     

    Another example is the documentation that came with a standard installation of python, it is in one place, categorizes the modules according to their usage, searchable and indexed. Although ActivePerl came with a better presented documentation, it's still less thoughtful than that of python, and that of the perl books, IMHO.
    Have you ever read
      perldoc perl
      perldoc perltoc
     Looks fairly well organized and indexed to me. As for "searchability", but I guess additions could be made to perldoc (grep works for me when I need it, or windows "File Find" thing).

     

    Now the goal of this post is not to complain, so please spare me the flames. I meant to ask, is there something we, as a community, can/should do to ease the pain of the beginners, actually also those of us less talented veterans. I truely believe all documentation is already there, it's just their organization, or lack of, that makes it less helpful. This is sort of like the web before google.
    I don't know what you're getting at. I do not think there is anything, we, as a community, can/should do to ease the pain of the beginners. The perl documentation is pretty well organized, and if that's painful, well, then you need some one-on-one attention, or you need one of the many products that deal with the documentation on cpan, like tkpod among others.

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.

[reply]

      What we perhaps need to do is to direct people towards perltoc instead of the relevant doc itself if it's obvious where to look after reading perltoc.

      ihb

      Read argumentation in its context!

[reply]
[d/l]
        What? That's just stupid. Why would Pod::Master be mentioned in perltoc? Why would you say look at the index instead of perlref or perlre?

        MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
        I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
        ** The third rule of perl club is a statement of fact: pod is sexy.

[reply]
Re: Perl documentation
by Arunbear (Prior) on Aug 13, 2004 at 21:10 UTC
    I truely believe all documentation is already there, it's just their organization, or lack of, that makes it less helpful. This is sort of like the web before google.
    It seems you are not aware of perldoc.com

    As a user of both Perl and Python I've found that the documentation of Perl's standard distribution is much more user friendly than its Python counterpart. This is most noticeable when it comes to code examples - they are as scarce in the Python docs as they are abundant in the Perl docs.

[reply]
Re: Perl documentation
by Your Mother (Archbishop) on Aug 15, 2004 at 06:25 UTC

    I do think the tool perldoc could be improved. For a language that is so DWIM, the tool is a bit obtuse.

    Wishlist: perldoc [arg] starts as normal. Looks for programs or modules in path of the name. Upon failure, reverts to -f behavior. Upon failure reverts to -q behavior. Upon failure goes to a new grep-like behavior through all the core non-module perldocs (perltoc, perltoot, etc) and gives an interactive menu of results to choose from.

    I know I'm probably not the hacker for this job, so I humbly de-volunteer, but I would sing loud and far the praises of anyone who patched it up to be so (and other features everyone deemed right and good).

    Better automatic access to the docs would probably save every guru in the community from issuing at least 5 RTFMs a year. If, like the CPAN, we could only bank it...

[reply]
[d/l]
[select]
Re: Perl documentation
by Wassercrats (Initiate) on Aug 13, 2004 at 02:35 UTC
    I'll just pick one of the many examples I could think of as an example of what needs improving in Perl's documentation. Where do you look when you want to learn about hashes? When I added hash support to VarStructor 1.0, I had to resort to a Perlmonks tutorial because I couldn't find the equivalent information in the perldoc.
[reply]
      Hmmm, perhaps perlintro which explains them and then says to see perldata for more?
[reply]
      A reply falls below the community's threshold of quality. You may see it by logging in.

Back to Meditations