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/
