Toby Corkindale over at The Dryft Net identified a very important problem that perl faces in his recent post for the Perl Ironman Challenge. Mainly, the usability of CPAN often acts as a barrier for new programmers getting into perl. CPAN, or the Comprehensive Perl Archive Network, is a completely open source, perl module library that is an invaluable resource for a seasoned perl developer. But for a new perl developer, CPAN can be extremely daunting.
“too often I am seeing users getting turned off Perl because the CPAN modules I direct them to are too hard to figure out. In turn, this puts the users off Perl. They really want to use the new modules, since they’ve heard good things about them, but they’re not going to go so far as to join IRC and/or read the source code to figure stuff out”
- Toby Corkindale at The Dryft Net
I easily could have been one of these porgrammers Corkindale is referring to, as a consumer of CPAN. In my early days with perl, there were several occassions where I broke down in tears of frustration when I wasn’t able to make some module work the way I thought it was supposed to, and the options available for figuring it out seemed so slim! Fortunately I was persistent and kept trying. Usually I would look for another way to do what I wanted, or occassionally I would look into the source, which was a very good way to learn perl. Since those days I have become very comfortable with CPAN, having used many different modules over the years. I have many times been grateful for the time and effort the modules on CPAN has saved me.
I have great respect for the CPAN contributors. Their efforts help make perl better for everyone else. I would hate to point a finger at these developers for the usability problems on CPAN. They do have a certain responsibility to ensure that their modules are documented sufficiently to be used by others when they are first released. However, the time commitment required to maintain the documentation of modules written years ago, while publishing new modules, and holding down that pesky day job, can be too much to expect. Nonetheless, we do need a sulution to imporve the usuability of CPAN if we want the perl community to grow, and I think I might have one.
Let’s give the consumers the opportunity to contribute to the knowledge base surrounding all of the modules on CPAN, thereby lifting the heavy weight off the original developers. Tagging, flagging, commenting, and embedded wiki sections on the module pages would enable the greater CPAN community to help out by sharing their experiences with specific modules. I call for the social web to come to CPAN. Its been long enough that perl belong just to the l33t.
Thoughts?
11 Responses
Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.
This would be outstanding, were it to happen.
Fortunately, the tools for enabling social web CPAN are on CPAN, as we speak.
Many of these features are already implemented. search.cpan.org will provide links to annotation, forums, source control (if defined in META.yaml), and several other community sites. The fact may be that people don’t use them unless they’re embedded in, but the features *do* exist.
“They do have a certain responsibility to ensure that their modules are documented sufficiently to be used by others when they are first released.”
No, the don’t! Code released on CPAN is a gift. If it has shitty (or no docs) it’s a poor gift, but that doesn’t mean you get to complain. If it’s not well-documented, don’t use it, or submit doc patches.
Nobody creating free software has any responsibility to other folks (except for not writing malicious code, I guess).
As the author of many, many CPAN modules, I find comments like this quite frustrating (and I _do_ write pretty good docs for most of my modules).
The cpan website definitely needs an update. It seems to be still stuck in the 90’s. I wonder who is in charge of it.
I have to agree with Dave: It is not my responsibility to make you understand how to use my module. I can’t divinely bless you with the brain power required. I write pretty damn good docs largely because I understand what /I/ look for when reading documentation: expected inputs, how outputs are coerced, and a little bit of broilerplate code to get started. That said, I am not going to hold your hand to get it working by writing a technical book in POD. If you feel the documentation is lacking, submit a bug via RT, email me, find me on IRC, shoot me an instant message, etc. Or better yet, send me patches!
The standard response to comments like these are: PATCHES WELCOME. Although, WELL VOLUNTEERED is gaining traction.
And if that is too hard for you, you can support my free/open software development with cold hard cash.
I think I agree with Dave and nperez – the point is that this ‘responsibility’ thing would create additional barriere to releasing modules, sometimes even undocumented modules are useful. We should not throw away usful code, we need better tools for searching and comparing the released modules.
search.cpan.org is closed source. I think that’s one of the reason why there is no improvement. I’d love to see ratings.cpan.org integrated in search.cpan in a way that you can simply click on one of 5 stars like every other web 2.0 page does it. I’d also suggest that ratings should be anonymous (at least one should have the choice). Ratings are a powerful tool to show popularity and point out shortcomings of certain modules.
Put search.cpan.org on github already!
Dave, NPerez, Please don’t shoot the messenger!
I think what Toby writes is a feeling that many people – maybe outside the inner circles of the Perl community – share. Your answers while valid sound really arrogant.
So maybe it is not our responsibility as it would be at a paid work. Please see the actual problem that this statement covers. In many cases the documentation is not good enough for beginners.
We should accept that this is the expectation of the more general public and do something about it.
That can be writing more docs by ourself but it can be educating them on how to improve the docs (as you also suggested), improving the AnnoCPAN integration – (is it used a lot ? do authors frequently incorporate the comments from there?)
It can be also in getting someone to sponsor the
writing of documentation.
Please listen to the voices.
Wow! I’m glad to see so many people agree with the sentiment of my post.
@ You have brought up two good resources: annocpan.org & cpanforum.com. CPAN could be so much better if these resources we more tightly integrated.
@Dave & @nperez your actions agree with my point despite the conviction of your complaints against my suggestion that developers have a responsibility to document their code. Having had a quick look at your contributions on CPAN you both have done an excellent job at commenting your modules (Dave Rolsky, Nicholas Perez). I am not asking for any more than explanations on what the
modules do, what the available functions are, and what their receptive parameters and outputs are. A programmer that does not document his/her code sufficiently enough to allow for people to use it, clearly does not care if people actually use the code. Why publish at all? Documentation is part of the code, and its quality reflects directly upon the author. It is the responsibility of any publisher, whether s/he be a programmer, journalist or novelist, to manage their reputation, by managing the quality their work. It seems to me that you both take this responsibility seriously, as you both put out quality work.
@Gabor Thank you for bringing the discussion back to the point. If we want perl to endure (ie. Still have good paying jobs in perl in 10-20 years from now) we have to consider these barriers. Specially when the new programmers coming out of school these days are acustomed to documentation standards of the Java API.
Hi,
I posted the original blog entry that Marilyn quotes from, and I just wanted to give a little more context to it, in the hope that CPAN devs will understand where I am coming from.
I like Perl, and CPAN, and want to keep using them both. Unfortunately in the commercial world Perl seems to be struggling – there are very few new people learning Perl, compared to other languages, such as Java, Python and Ruby. This makes it hard to hire new Perl developers, and hard to sell Perl to management and/or clients. In fact, the last (large) company I worked at embarked on a massive campaign to rewrite their entire system in just about everything *except* Perl.
I want to evangelise Perl, especially *modern* Perl, which means well-written OO Perl with innovative CPAN modules.
Unfortunately, I keep suggesting people try things out, only to have them get fed up because they can’t work something out from the docs. As I posted originally, the docs are often complete and DO have the info required.. it’s just that to find it requires too much knowledge. ie. The documentation is often aimed more at developers than users, or without an understanding of how users USE the docs.
This isn’t the fault of the developer of the module developers, but I’m trying to raise the issue as a problem we need to deal with, if we want Perl to get taken seriously compared to other languages, which have higher doc standards.