in reply to Perldocs and peer reviews

As a CPAN author, I appreciate feedback from users. But I'm not waiting for people who after "skimming" the docs, tell me they find them unclear, or find the the described syntax nonintuitive or unfriendly.

Really, I spend a lot of time working on my code and the documentation. The least I expect of a user is to spend a little time with the module before critizing it. What might not be clear after just skimming the docs, might make a hell of a lot of sense if you actually use the module.

Feedback is good, but bad feedback is worse than no feedback.

Replies are listed 'Best First'.
Re^2: Perldocs and peer reviews
by g0n (Priest) on Jan 31, 2005 at 15:06 UTC
    Mm, not an aspect I'd considered, I must admit.

    However, I'm not sure I agree that bad feedback is much worse than no feedback. A trollish or daft feedback mail can just be binned. How much notice to take of feedback is a judgement call on the part of the author. If you are getting helpful feedback from a range of regular users, then a POD skim is not likely to be helpful.

    On the other hand, for those of us (raises a timid hand) maintaining 'niche' or new modules, which don't have a significant user base, feedback saying 'xyz is not really clear/your constructor syntax is difficult to follow' etc might be of help.

    I come back to the comment earlier in the thread - I'm not suggesting that we replace the process of CPAN testing, but widen the range of QA by looking at the POD of distributions that otherwise might not go through any other public testing.

    VGhpcyBtZXNzYWdlIGludGVudGlvbmFsbHkgcG9pbnRsZXNz
[reply]

      A trollish or daft feedback mail can just be binned.

      That doesn't mean we should encourage people to send more superficial feedback in the hopes that some of it will be useful, though.

      Makeshifts last the longest.

[reply]
      A trollish or daft feedback mail can just be binned.
      Yeah, and so can spam. Trollish or daft feedback still require the author to read the reply. It's still a nuisance and it disrupts the process.
      feedback saying 'xyz is not really clear/your constructor syntax is difficult to follow' etc might be of help.
      might be is not good enough. You might be helped by such feedback, but I certainly am not. Unless you can specify why it's not clear or difficult to follow, and what the alternatives could be, I don't know whether you simply don't know Perl very well ("not clear" and "difficult" is subjective) or perhaps you do, but you don't really know the module I wrote very well and what you think would be simpler would mean loss of functionality.

      That's bad feedback, and is, IMO, worse than no feedback. It's just like questions. A wrong answer is worse than no answer at all.

[reply]

In Section Meditations