On 10 January 2013 02:05, Levi Morrison <morrison.l...@gmail.com> wrote: > Firstly, I apologize if this is the incorrect list.
It's more phpdoc and php-notes, so I've cc:d those lists in. Thanks for pitching in! Here's some background reading from a user note discussion last year: http://marc.info/?l=phpdoc&m=134639945511076&w=2 — I also reviewed a whole heap of notes to try to categorise them, except I was trying to kill the feature totally. :) (I got better.) There have also been a bunch of IRC discussions on #php.doc at various times around user notes. I'm trying to crystallise my understanding of those below, but I expect other people will disagree with me. > 1. Code snippets to do something similar to the current function. > 2. Reports of performance compared to function X. Incorrect > testing methods are usually involved. > 3. Reports an edge-case not included in the manual section. > > Some pages of the manual have severe problems with #1. See > http://php.net/manual/en/function.count.php for an example one such > page. A blanket policy of deleting notes like this would probably be > harmful, but on this page in particular I feel like deleting all > comments of this type. > > What really bothers me about #2 is that the testing methods are > usually skewing the results. I don't feel like editing is appropriate > in these situations but am unsure if deletion is appropriate either. When in doubt, we generally tend towards deletion. (I probably have the heaviest hand of anyone on this front, but I'm not alone in the philosophy.) If you look at the archive of the notes ML, you'll note that periodically, someone (probably Sherif, Dan or I in recent times) will get frustrated with the state of a page and will cull the worthless notes. On bigger pages, that's often 50+ notes. It sounds like count() is due for that. > In the case of #3 I feel like we should simply update the manual. The > question then becomes: should we keep the comment? Generally, no — if the manual's been updated, then the note should be removed. > Related: is there a posted guideline for moderating user contributed notes? We don't have a lot written down that I'm aware of. My own opinion is: - Questions and support requests should be rejected (so that the submitter gets an e-mail). - Useless notes get deleted. Defining useless is left as an exercise for the moderator, although the quick deletion reasons in the automated note e-mails do provide a rough guide (they are: integrated, useless, bad code, spam, non-english, in docs, other reasons). - Real bugs get turned into bug reports, then deleted. - Responses to previous notes should usually result in the previous note being edited or deleted, and the response being deleted, since user notes aren't intended to be a conversation thread. That doesn't tend to leave a lot, admittedly. (Which is one of my frustrations with the whole feature.) Thanks again, Adam
