The user contributed notes at php.net have recently undergone some changes last week as user voting was integrated into the manual. So far this feature seems to grabbing the interest of thousands of users on the site as voting was made very simple (there's no need to leave the page in order to vote) and very open (open to anyone).
Key motivators behind improving the user notes system include improving the documentation, spotting mistakes in the existing documentation that the documentation team hasn't, and weeding out the bad notes that need moderated/edited or removed. Here are some interesting figures on user notes that I've dug up. - There have been over 110K notes submitted to the manual in the last ~14 years. - There are over 26K user submitted notes currently in the manual today. - 75% of all the notes submitted to the manual are eventually deleted or removed. - 11% of all the notes in the manual have been voted on in the last 11 days, alone. - 53% of those votes were positive while 47% were negative. - 47% of all the notes, that were voted on, currently have a positive rating. - 45% of all the notes, that were voted on, currently have a negative rating. - 8% of all the notes, that were voted on, currently have a neutral rating. - 4% of all the notes, that were voted on, currently have a positive rating of +3 or higher (meaning the total number of positive votes they received exceeded the total number of negative votes they received by at least 3 votes). - Only 2% of all notes, that were voted on, currently have a negative rating of -3 or lower (meaning the total number of negative votes they received exceeded the total number of positive votes they received by at least 3 votes). Overall, what this means is that we have way more eyes and hands on user notes now than we ever did before. Users are no longer spectators in php.netuser contributed notes. They are active players moving the good notes into the spotlight and driving the bad ones away. There are already good examples of how this system has helped improve the manual. A user contributed note from several years ago on the print_r page made a contradictory claim to the documented behavior of that function. It turns out the user note was correct and the manual was wrong: http://svn.php.net/viewvc/phpdoc/en/trunk/reference/var/functions/print-r.xml?r1=297028&r2=328776 Since users were able to spot this important piece of information and collectively voted the note up to the top of the page I happened to spot it and realize that the manual needed updated. The note served a benefit to the manual in that situation, but what surprises me is that note had been there for over three years without anyone on the documentation team spotting it and realizing it should have been integrated into the manual. This was a problem with the old system since good notes could easily get buried under years of other notes that may or may not have useful information. My take from this is that the community driven effort of having more than one pair of eyes as well as more than one pair of hands to assist in cleaning up the manual has certainly proven beneficial in the short term. The key focus now should be on what steps can be taken to ensure this good measure is sustained and focused on further improvements. A great big thank you to everyone that has been helping out with user notes and moderating the notes. A special thanks to everyone that allowed me the opportunity to help improve the system, if even just slightly, and provided guidance and much needed support. Especially to Philip and Hannes for their input, Derrick for helping me get the database table setup, and Adam and Dan Brown for all their time spent weeding out the bad notes, fixing up the not so bad ones, and even making the good ones better.Of course everyone else I forgot to mention. ---- Sherif, The one that always seems grumpy, but really isn't...
