Re: User notes

On 31/08/12 08:50, Adam Harvey wrote:

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%

This mirrors my experience.

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. No change sounds bad. There's a lot of bad stuff in there, and it's worrying that right next to official PHP documentation with plenty of good advice, warnings, and best practices, there are tons of user comments that are unhelpful or even harmful, often solving the wrong problem, or if solving the right problem, doing so quite badly.

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. This is what I'd like. I don't think we should have comments in a *manual*. They usually aren't helpful. If something's missing from docs, it should be added to them, not commented.

Now, what about dealing with the code-snippets for newbies? For that, I like Lars Schultz's "Official Userland Library" idea, from 2012-08-20 (11 days ago). Having a well-curated library of snippets is helpful (even I would appreciate them from time to time!), but the current mess of user notes isn't. Of course, we could copy some of the rare, good solutions from those notes to the new "Official Userland Libary", and attribute them as apropriate.

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?). I don't think that would really change much.

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. Fair enough.

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

-- Andrew Faulds http://ajf.me/