tl;dr: I am become death, the destroyer of user notes. (I hope.) Hi everyone,
As many of you know, user notes have been a long-standing hobby horse for me. About six weeks ago, I decided to do something useful about them, and subscribed to the mailing list to try to help moderate the stream of incoming user notes more effectively. My opinion of user notes was already that they were generally not particularly worthwhile, but a few weeks of consuming the firehose has changed that. I now think they're actively harmful. To illustrate my point, here's a breakdown of the last 200 submitted user notes: Type Notes Percentage Non-useful code sample 39 20% Something already in the manual 26 13% Support request 25 13% Reply to previous note 22 11% Actually useful note 16 8% Documentation bug report/improvement 13 7% Useful code sample 13 7% Not PHP related at all 11 6% Correction of previous note 9 5% WTF? 9 5% Bug report 8 4% Link to unrelated site/spam 5 3% Link to related site 2 1% Duplicate 2 1% Now, obviously the categorisations are subjective. I tried to be as generous as possible when rating a note or code sample as useful: if it was something that I considered obvious or was documented elsewhere, but wasn't really dealt with in the section the note was in, I considered it useful. By that metric, about 15% of the notes submitted are actually of real utility. That's a lot of noise and not much signal. The added problem is that a lot of the non-useful samples aren't just poor quality. Many are genuinely harmful: they include poor security practices, deprecated code, and various other things that, unfortunately, being on *.php.net masks, since many users give user notes equal authority to the manual itself. Plus I can see three possible ways forward: 1. No change. As things stand, the only people who seem to look regularly at the new notes are Dan and myself, with a few others (including Sherif, Nikita and Peter) cleaning out particular pages. If you pick a reasonably commonly hit page and look at the user notes, I don't think this approach is scaling. 2. Kill user notes completely. The new site design (I'm getting to that in another e-mail in the not-too-distant future, hopefully) has more prominent links for reporting bugs and going to the online editor, so I'm hopeful that we might actually get the useful feedback listed above via those means instead, and can then incorporate them into the manual proper. 3. Replace user notes with something more comment-based: either something on-page like Disqus (which probably doesn't get us much other than comment threading for better conversations and a shitty UI), or linking to something like StackOverflow (maybe we see about getting a PHP-specific, officially-blessed StackExchange, with links from function references to tags?). One road I don't particularly want to go down is adding significant additional functionality to our own user notes: our backend would require a decent amount of work, and I think there are better solutions out there we could leverage. Thoughts? Am I completely on the wrong track? Are the PR benefits of user notes enough to outweigh the amount of crap^Wnoise they contain? Thanks, Adam
