On module reviews

In retrospect, I believe made an error in judgement with my 'review' of Getopt::Declare. After seeing tilly's response I realize that I didn't address some fundamental questions that are common to most analytical reviews: description, the good, the bad, etc. Instead, my brain was more in tutorial/quick-start mode than review mode.

Now, I don't think it is show-stopping blunder, and the module is at least introduced and described, but it is not an analytical review by any means. However, heading over to the Tutorials section, I find we don't really have a place for module introductory tutorials. Certainly some tutorials use modules, but it just doesn't quite seem the appropriate place for a bunch of basic module tutorials/introductions (I could be wrong, it has happened before).

So here is my (discussion|meditation): might it be a good idea to organize the module review section categorically into analytical reviews and tutorials (jump starts)? Perhaps using a 'Review' or 'Tutorial' tag in the submission form. I don't envision two pages, or all reviews at the top and tutorials at the bottom, but rather something like:

   * Some::Module
        Review: by someone
        Review: by someone_else
        Tutorial: by yet_someone_else

   * Some::Other::Module
        Review: by someone
        Tutorial: by some_one
        Tutorial: by Some_one_else
[download]

And make the Module name itself a link to cpan, and each 'Review' tag a link to the actual review. Of course, the tutorial entries could also be cross-linked from the Tutorials section.

Extending this basic idea, it might also be nice if CPAN search engines also provided links to such reviews and tutorials -- so if someone searched for Some::Module they might see:

    Some::Module blah blah description [documention]
        contained in: Some-Module-2.14 [download/quickinstall]
        Category >> Misc >> Something
        
        PerlMonk Reviews and Tutorials:
            Reviews: [by x], [by y], [by z]
            Tutorials, [by x]
[download]

The above is following the basic format of an entry turned up by this engine -- the 'by x' would link to the review (not the author's homenode). Any engine could add such info and a summary (RSS) of the reviews page could make it that much simpler).

I know Randy Kobes (author/maintainer of the above mentioned search engine) so I can bring this up with him at our next Perl Monger meeting at the end of Feb.

What are other Monk's thoughts about a) reorganizing the reviews section by reviews vs. tutorials, and b) getting these linked from CPAN queries? (I know I'd appreciate quick links to reviews and tutorials when I'm searching CPAN for something).

Comment on On module reviews Select or Download Code

Replies are listed 'Best First'.
Re: On module reviews by footpad (Abbot) on Feb 04, 2001 at 02:31 UTC
Why not simply create a section in Tutorials for Module Tutorials and request that your node be moved to it? That would be the first place I would look for such documents. I would prefer that Reviews tell me who wrote the module, what it tries to do, whether or not it succeeds, and whether or not the reviewer thinks it's worth installing. I like your idea about beefing CPAN's searching capabilities, but I'm not certain it's entirely fair to ask them to include just our little Monastery. While we all know this is the best place for Perl-related assistance, I'm not sure the rest of the Perl community would be so discerning. If they were also willing to broaden the range of included sites, I think that would be more than fair, though I confess that I'm not sure what the impact would be on their servers. (Perhaps they could use something based on merlyn's recent article.) I do think, however, that someone who created a CUFP that searched CPAN and included that sort of summary would get more than a few votes, as well as some valuable experience. --f	[reply]
Re: On module reviews by mirod (Canon) on Feb 04, 2001 at 02:52 UTC
My take on Module Reviews is that a lot of the modules on CPAN have fairly good documentation, including tutorial-like introduction. What they lack is 3rd-party evaluation. Something along the lines of "don't use this module under windows" or "I found this module worked fine under mod_perl", or even "this module has some flaws but I found it worked for me in most situations" or "this module is hopelessly bugged and the author never answered my email". That's what I appreciate in Module Reviews: a user view on the module. If I determine from the review that I can use the module to solve my problems then most of the time I will figure out how to use it. Oh, and non-obvious tip is welcome too of course.	[reply]
Re: On module reviews by danger (Priest) on Feb 04, 2001 at 02:56 UTC
A new module tutorial section under Tutorials is certainly a possibility -- though if that get's implemented, I'd still like to see cross-links stuck in the module review section (see also these tutorials or something) so if I'm browsing through module reviews I could also easily hit tutorials. As for CPAN search results pointing to reviews and tutorials, I didn't mean to imply that only PerlMonks would or should be linked to, but that would be a good first step -- if the search engine authors/maintainers can agree on a mechanism (and there are only two main CPAN search engines I can think of: search.cpan.org, and theoryx5.uwinnipeg.ca/CPAN/cpan-search.html), then any other site (perhaps perl monger group sites) could also export a summary (or whatever) so that their reviews get into the databases to as well. At any rate, current replies suggest keeping reviews strictly reviews and putting any module tutorial type things under tutorials. So perhaps this is the better idea. I will submit a request, as suggested by footpad, to create such a section and to move my Getopt::Declare posting there. Thanks for the feedback.	[reply]
Re: On module reviews by flay (Pilgrim) on Feb 04, 2001 at 02:36 UTC
I can see your point, but I feel that putting anything that is basically tutorial in nature in reviews is only going to confuse. An extra sub-heading under tutorials for `Modules' could offer both basic and more in depth guides to using them, and would be a more logical grouping than splitting reviews into reviews and things that aren't reviews. As for the CPAN suggestion, it's not a bad idea, but would be better generalised to tutorials anywhere, not just in the Monastery. Your suggestion didn't preclude that, of course, it just makes for a stronger case. -- Tom Waddington	[reply]