I saw AnnoCPAN mentioned on the perl.it "blog". It looks interesting. But the people submitting comments to it would do better to submit documentation patches to the module authors.
As an example, this comment is very useful, but really, it should be in the POD so that it is installed on my machine for me to look at without having to dick around with tha intarweb.
Re:Easier is different, too
drhyde on 2005-07-01T10:17:41
Submitting docpatches isn't hard. I know, cos I've done it. It's a mere matter of looking for the author's email address in the POD and suggesting a change. You don't need to send a diff or anything. It's far easier than finding the web site, searching for the module, trying to log in, forgetting your password, and so on. I'm all for making it easy. Which is why I'm all for people emailing docpatches.I wouldn't know AnnoCPAN existed unless I read the Italian Perl Mongers' blog, and how many module authors (especially US authors) would do that? There are still people who don't know that CPANratings exists. Hell, there are even module authors who don't know about rt.cpan.
AnnoCPAN is pointless, because it's *harder* to add an annotation than it is to submit a docpatch properly by email. It's also pointless because no-one will think to use it to look for clarification of problems they're having. And it's also pointless because module authors won't look at it to see if anyone has used it to submit docpatches.
Re:Easier is different, too
sigzero on 2005-07-01T12:17:11
Pointless? Seems to work for the PHP really well.REALLY well
davebaker on 2005-07-03T00:42:18
I agree!Re:Easier is different, too
itub on 2005-07-01T13:11:44
Who knows, only history will tell if it is really useful or not. I believe it will, and that's why I worked on it.AnnoCPAN was officially announced to the world two days ago, so the fact that you already heard about it is actually a good sign.
;-) The main reason I think it can work better than sending an email to the author of a module is because it provides instant gratification--you add a note, and there it is. If you send an email to the author, assuming that he reads his CPAN email, likes your suggestion and decides to add it, you still usually have to wait weeks until the next release, because few authors will bother with uploading a new version because they added one little paragraph to the POD. After that, everyone will have to upgrade their module to see the change (and most people never upgrade a module that works).
Another reason is that not all notes are necessarily worthy of making it to the official documentation, even if they are useful. They may be interesting footnotes, but that would be distracting if they were inserted in the main text.
Will authors look at the notes people post next to their modules? I'm sure some will and some won't. I'm planning to add RSS by author so that those who want can be notified more efficiently. I could send all authors automated emails, given that the emails for all CPAN authors are available, but I'm sure not everyone would like that...
Re:Easier is different, too
autarch on 2005-07-01T18:44:44
RSS by author would be great. I definitely want to track annotations on my modules, but it's got to be convenient.Re:Easier is different, too
itub on 2005-07-01T22:13:23
Done. See http://annocpan.org/user/drolsky/recent.rss , for example.Re:Easier is different, too
autarch on 2005-07-02T04:02:36
Wow, now that's service.
Ok, now how about some house-cleaning, cooking me some gourmet vegan meals, and... Re:Easier is different, too
drhyde on 2005-07-04T10:36:49
I would love to get email notifications - I get them already when people report bugs using rt.cpan, and I didn't ask for that. Such emails wouldn't normally be classed as spam if that's what you're worried about - spam is defined as being unsolicited bulk email, and this wouldn't be bulk.An alternative would be for you to automagically populate RT with these suggested documentation updates.
