Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

Yet Another YAPC entry 5 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.

  • And if you are going to say something have the courage to put a name to your spite.

    I heckled him because he was wrong, so wrong that it wasn't possible for me not to. For all I know, this person is you. I wrote much of and keep the CPAN and search.cpan FAQs, I run the box, I keep it running, and we answer and address feedback as time and patience allow. When some guy starts bitching about how 'this page has no links' or 'this has no FAQ', etc. when that person hasn't sent email to said effect, he's lucky

    • I liked the part where the guy showed a page and said "why isn't there a FAQ link here?" and you pointed out the FAQ link right there on the slide.

      He was a tool. You were just culling the herd!

      • Just a slight disagreement with you here. I believe that this is the slide you were referring to:

        http://omor.com/perl/yapc2002l/8.html

        I thought that David Crawford was perfectly clear in his remarks that what he wanted was an FAQ about XML-RSS (the module that he used as an example). The FAQ link that Ms. Ashton referred to is a search.cpan FAQ, not specific to XML-RSS. His point was that it was difficult to figure out if XML-RSS would solve his problem -- not that it was difficult to figure out wh

        • And how, praythee, is either search.cpan.org or CPAN supposed to be offering a module-specific FAQ if there isn't any...? (If there are other doc files available, like for example HTML files at the top level of the module, search.cpan.org does list them, try for example distribution 'CGI.pm'.)

          Mr Crawford's talk was titled "CPAN is unusable". If his point really was to complain that XML::RSS should have an FAQ, that title is, ummm, oddly chosen. In any case, all this talk was to bumble around in the per

          • Thanks for the note. Perhaps at this point I should distinguish two things that I may not have stated well:
            1. I don't think people should heckle others during presentations. Giving a presentation in front of 300 of your peers is stressful -- getting heckled increases the stress by an order of magnitude. Be polite to your fellow Perl-ites. Period. (Clearly Jarkko, this is not directed at you.)
            2. I think as a community we should be open to public critiques that say that CPAN (or other open source software) could be made more usable to relative newcomers. This is how I interpreted Mr. Crawford's talk -- I don't think it was an attempt to give cheap digs to folks who give substantial amounts of their time to the good of the community. (Jarkko -- I hear you saying that you're open to those critiques, but I disagree that Mr. Crawford failed to provide them.)

            I have just re-read Mr. Crawford's presentation. (Here's a link: http://omor.com/perl/yapc2002l/)

            Here is a synopsis:
            • I read something about an interesting technology -- (RSS as an example in this case).
            • I go to search.cpan.org and search by keyword. I get lots of results. Cool!
            • I choose XML::RSS, and I get a page with lots of links.
            • I choose the link to the pod that describes the module. It has no navigation, no links for download or install.
            cbrooks:
            Why shouldn't the pod include some navigation? It's just html -- presumably search.cpan has access to mod_perl. Why not add a consistent header to every page? In particular, a link that says "download" would improve the usability of the page for folks that aren't used to the existing layout.

            Continuing the stream of Mr. Crawford's presentation....
            • Not knowing exactly what to do at this point, I back up, returning to the set of modules that =~ /RSS/
            • I click on the XML::RSS link that doesn't include the version, and I go right back to the pod.

            cbrooks:
            Doh! Well, that would be kind of frustrating. Wouldn't it be helpful if the search.cpan search results were a little more clear? Perhaps the link to the pod should be eliminated. Or perhaps links to the README and download options should be included. The point remains -- those search results are a bit confusing.

            Blithely continuing with Mr. Crawford's presentation:
            • Now I go back to the module link that includes the version. The words "download", "install" and "manual" do not appear. (As I recall, this is where he made his infamous comment which Ms. Ashton took out of context re: there should be a link for an FAQ.)


            cbrooks:
            Actually, "download" and "manual" would be useful additions to this page. I would argue that the extra bytes that they entail are more than compensated for by the additional clarity they provide. Presumably his comment about a link for "install" would link to an INSTALL file, if one were available in the package. Not a bad idea, although I would suspect that "Installation instructions" is a bit more clear. It does not appear to me that search.cpan adds this link if an INSTALL file exists -- see, for example, Apache::Session.

            Back to Mr. Crawford:

            • Docs available only if you download and install the module do not help you do decide which module to get.

            cbrooks:
            That's a fair point. However, the problem is that (unlike his previous points) there is little that search.cpan can do about this. If the module's author doesn't provide a clear description in the pod or the README file, you're sort of stuck. Same with his FAQ comment.

            Continuing....
            • Some other comments about searching modules by category, and the way that Perl assumes XML::RSS is in the directory XML/RSS.pm

            cbrooks:
            I don't actually remember this from his lightning talk -- did he scrap it? If not, I'll agree -- I'm not sure that this is a useful critique.

            Finally:
            • SOAP::Lite has a very nice interface for a user trying to figure out what to do.

            cbrooks:
            Yup. Quite nice. Note at least three of his earlier critiques that could be done by search.cpan, but are not:
            1. It is very clear how to download the module.
            2. There is a "Usage" link (perhaps a better replacement for the "Manual" link that he had mentioned?)
            3. There is an "Installation" link.
            I have a couple of other usability suggestions:
            • Why couldn't search.cpan strip off the trailing ".pm" if you include it in your search criteria? For example, a search for CGI.pm shows 0 results. Kind of confusing.
            • If you search for "CGI", you get many, many results. Perhaps search.cpan could apply some heuristics which attempt a better search order. For example, perhaps the shortest module name should appear first, on the theory that modules that extend it will have longer names? Or perhaps the oldest modules should be presented first? Or perhaps the user should get to choose how to sort?


            Anyway, this is a rather long reply, so let me sum up. I think Mr. Crawford had several good points that would substantially improve the usability of CPAN. However, I don't believe that he received the kind of respectful treatment that he should have, given that he pointed out some genuine short-comings.
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.