in reply to Got Perldocs?

I've long been a frequent searcher and reader of CPAN Search and Randy Kobes' Search.

Lately, though, I've been hanging out on AnnoCPAN, where you get not only a module's POD, but the opportunity to annotate the margin next to it, and of course to read others' comments. It's a great place to find tidbits you might not get from the docs themselves, as well as for module authors to incorporate these notes into the POD for future releases.

Replies are listed 'Best First'.
Re^2: Got Perldocs?
by gellyfish (Monsignor) on Sep 08, 2005 at 23:31 UTC

    AnnoCPAN might be a great idea, however it doesn't appear to feed back any annotations to the module authors, indeed it has a big block at the top saying:

    Is AnnCPAN a substitute for proper bug reports? No. If you want a bug to be fixed, or you would like a change in the official master copy of document, please follow the proper channels.

    So don't rely on it getting back into the documentation of the module, and don't rely on it not becoming outdated when some bad module author goes and changes the whole documentation under its feet.

    The best way to get a change to the documentation of any module I maintain is to send me a unified diff against the current version.

    /J\

[reply]
      I added that disclaimer at some authors' suggestion. However,
      • AnnoCPAN does send an email notification to authors whenever someone posts a note to their modules (it's opt-in after the first email).
      • If an author changes the master documentation in response to a note, the note won't show up when viewing the documentation for the new version of the module (It usually guesses automatically when it shouldn't be shown, but when it doesn't guess right the note can be hidden manually. If I've missed one please let me know.)
[reply]

In Section Perl Monks Discussion