Eric Wilhelm wrote:
# The following was supposedly scribed by # Randy W. Sims # on Saturday 24 July 2004 03:06 pm:
If it does get added, does it get added to all the documentation pages or just the main documentation page?
Could you give an example of what is 'main'? I mean the page with the rendered version of the pod. On my tour, I clicked the bigger-bolder link above the search-result entry (http://search.cpan.org/~lds/CGI.pm-3.05/CGI.pm) not the smaller-seemingly-less-important one below it (http://search.cpan.org/~lds/CGI.pm-3.05/).
If you look at the page linked to by the "less-important" url, you'll see links to all the pod docs for that module. I was asking if you intended that the ratings be added the headers of all of that modules docs.
To me, the former contains information which will let me make an informed decision about the module (e.g. the programmer's reference to the API which it provides) while the latter gives lots of links, ratings, test results, and related stuff, but only tells me this about the module in question: "Simple Common Gateway Interface Class" and I have already seen that exact information in the search-result entry.
The latter links to all of the modules docs, the README, META.yml, etc. for all versions of that module. It's provides a junction point that leads to all info on that module. This is always the first place I go. I look at the README first, then the main pod. Then I can look at the META.yml if I need to check out dependencies, etc. before installing.
One other thing to consider: if ratings are added to the search results page, eg. <http://search.cpan.org/search?query=CGI>, then placing them on the documentation page is duplicating info that has already been made available.
[snip]I would also like to see a simple yes/no count in addition to the rating/reviews. If you have a list of "35 people use this::module" and "700 said 'use this::other::module instead'", that helps raise awareness about the other module, and allows you to make a decision more quickly based on the experiences of others.
Are you referring to the amazon.com-ish "N persons recommend X instead of (or in addition to) Y" type recommendations? I'm not sure CPAN is worth the added complexity. I don't think the target audience is big enough to justify a lot of "extra" features; the ratings should be enough, but I could be wrong...
I'm not sure right now how useful it would be or how many others would find it useful, but yes the N,X,Y is along the lines of what I mean. The reason that I mention it is simply that I had the idea that it might be useful in selecting modules (yes, it's a popularity contest and should be ignored in favor of an informed decision based on reading the manpage, but we can't ignore information that isn't there.)
I'm sort of groping for something to 'season' the average-rating. Since I am suggesting that the average rating be displayed at the top of the manpage, I thought I should provide an idea which would allow it to mean more than 5/5 (e.g. one person rated it 5/5: 'big whoop'.)
agreed. I think where ever "average" ratings are displayed it should include the number of reviewers, eg "this module rated 4.5 stars by N reviewers".
I think '600 people said "it's useful"' may be more helpful than one mediocre review. 60 raving reviews would tend to bend your decision more, but it's easier to get 600 people to say 'ok' than it is to get 60 to say 'this-is-great-and-here-is-why'.
I'm worried about some of the items that are on the list. Some that seem obvious like adding ratings to the search results on Search I'm not sure about any more. If ratings are used to compare modules (as opposed to judging each according to its merrits), some modules might be overlooked, especially new modules. Are ratings usefull? I won't argue that reviews are usefull. And ratings provide a summary of reviews, so are helpfull in that respect. But can ratings be harmfull? ...
Randy.
