4 ms·

In general, I find Perl's CPAN to usually have really good documentation that surpasses what Python has, even though I prefer Python over Perl nine times out of

In general, I find Perl's CPAN to usually have really good documentation that surpasses what Python has, even though I prefer Python over Perl nine times out of ten.

kbenson 8y ago
As a full time Perl developer, I've wondered more than once if this is due to the way the way the language shapes the community. Perl has evolved (out of necessity) a very strong level of norms and best practices that users are aware of, and put effort into following (well, most the time, Perl is all about letting you pull out the shiny weirdness and letting it shine where it fits well). Module documentation is part of this. A module could implement an object oriented interface, a procedural interface, both, import function into the main scope on use, or on request, or any number of weird (and depending on your point of view wonderful) things. Not having good documentation means nobody knows how to use your module without a lot of work reading the code. So modules get documented or they get ignored. Thus, the modules on CPAN you know about and that are commonly used and relied on by other modules are the ones that have good documentation. It's self reinforcing. I imagine in a language that funnels use into a single or small set of idiomatic ways to accomplish most tasks, it might be easier to skimp on documentation and rely on people to fall back on the "obvious" way to things.
- 4thaccount 8y ago
  I'm not a full-time Perl Dev like you, but do whip up something a few times a year and it is there when I need it. I'm therefore incapable of properly replying to your thoughts although it makes sense to me (Perl is so flexible that you better have good documentation if you make a module and want it used). My thoughts are more along the lines of how much modules and CPAN are pushed in general. Most of my Perl books (Ovid's in particular) go into excruciating detail on publishing packages. It's not a two pager crammed into an appendix either, but is front and center. The Perl community frequently hosts challenges to clean up old modules and such. There is even a guy with the last name of "Anwar" if I recall correctly that is a celebrity in the community for how many modules he maintains that aren't even his (and he has also done challenges like making a new pull-request every day for like a year). That is some real dedication there to making Perl useful. It is one of the things I really like about the community. I'm a little bit of a language hobbyist even though I'm still only a novice coder in my mind. Out of all the languages that I've spent time with (probably 2 dozen) learning superficially, I'd say Perl ranks towards the top of the spectrum when it comes to focusing on this. They've evolved a relatively simple and effective system for allowing users to make, share, and document libraries.
  - kbenson 8y ago
    > They've evolved a relatively simple and effective system for allowing users to make, share, and document libraries. Well, as is often said, simple is not easy. :) There's a large effort by the CPAN testers community to run every module (and every new version of it) against a large array of hardware and operating systems[1], and provide automated reporting to the author of any problems. This is possible because of (and incentivizes) the other great aspect of CPAN and the public modules which are on it, which is a strong culture of good test coverage of modules, and the CPAN clients running all tests and failing to install by default if any tests fail that weren't expected to. It's another wonderful feedback loop, and one not encouraged or discouraged by most languages specifically, so the fact that so many package managers for languages decided not to do so is unfortunate. When you don't start with that as an expectation, turning it on at a later date likely just results in a horrible user experience as a large number of module just fail to install (or at a minimum spew warnings which are confusing) because they are exposing what was previously something only the author saw most the time. 1: http://matrix.cpantesters.org/?dist=Path-Tiny+0.104 http://matrix.cpantesters.org/?dist=Path-Tiny+0.104
    - 4thaccount 8y ago
      Thanks for the helpful replies. I didn't know that.

In general, I find Perl's CPAN to usually have really good documentation that surpasses what Python has, even though I prefer Python over Perl nine times out of ten.

kbenson 8y ago

As a full time Perl developer, I've wondered more than once if this is due to the way the way the language shapes the community. Perl has evolved (out of necessity) a very strong level of norms and best practices that users are aware of, and put effort into following (well, most the time, Perl is all about letting you pull out the shiny weirdness and letting it shine where it fits well). Module documentation is part of this. A module could implement an object oriented interface, a procedural interface, both, import function into the main scope on use, or on request, or any number of weird (and depending on your point of view wonderful) things. Not having good documentation means nobody knows how to use your module without a lot of work reading the code. So modules get documented or they get ignored. Thus, the modules on CPAN you know about and that are commonly used and relied on by other modules are the ones that have good documentation. It's self reinforcing. I imagine in a language that funnels use into a single or small set of idiomatic ways to accomplish most tasks, it might be easier to skimp on documentation and rely on people to fall back on the "obvious" way to things.

4thaccount 8y ago
I'm not a full-time Perl Dev like you, but do whip up something a few times a year and it is there when I need it. I'm therefore incapable of properly replying to your thoughts although it makes sense to me (Perl is so flexible that you better have good documentation if you make a module and want it used). My thoughts are more along the lines of how much modules and CPAN are pushed in general. Most of my Perl books (Ovid's in particular) go into excruciating detail on publishing packages. It's not a two pager crammed into an appendix either, but is front and center. The Perl community frequently hosts challenges to clean up old modules and such. There is even a guy with the last name of "Anwar" if I recall correctly that is a celebrity in the community for how many modules he maintains that aren't even his (and he has also done challenges like making a new pull-request every day for like a year). That is some real dedication there to making Perl useful. It is one of the things I really like about the community. I'm a little bit of a language hobbyist even though I'm still only a novice coder in my mind. Out of all the languages that I've spent time with (probably 2 dozen) learning superficially, I'd say Perl ranks towards the top of the spectrum when it comes to focusing on this. They've evolved a relatively simple and effective system for allowing users to make, share, and document libraries.
- kbenson 8y ago
  > They've evolved a relatively simple and effective system for allowing users to make, share, and document libraries. Well, as is often said, simple is not easy. :) There's a large effort by the CPAN testers community to run every module (and every new version of it) against a large array of hardware and operating systems[1], and provide automated reporting to the author of any problems. This is possible because of (and incentivizes) the other great aspect of CPAN and the public modules which are on it, which is a strong culture of good test coverage of modules, and the CPAN clients running all tests and failing to install by default if any tests fail that weren't expected to. It's another wonderful feedback loop, and one not encouraged or discouraged by most languages specifically, so the fact that so many package managers for languages decided not to do so is unfortunate. When you don't start with that as an expectation, turning it on at a later date likely just results in a horrible user experience as a large number of module just fail to install (or at a minimum spew warnings which are confusing) because they are exposing what was previously something only the author saw most the time. 1: http://matrix.cpantesters.org/?dist=Path-Tiny+0.104 http://matrix.cpantesters.org/?dist=Path-Tiny+0.104
  - 4thaccount 8y ago
    Thanks for the helpful replies. I didn't know that.