Well, I like to start by looking at the existing system.
So from a quick analysis, the types of user notes we currently see
are:
Comments to enhance the documentation: i.e. expanded code examples,
use cases.
It's tough to come up with [most] all possible subcategories here but
notes about tips and gotchas also come to mind.
Comments to correct the docs: fix typos, report changed behaviour
As you stated the online editor should help with this, as soon as we
determine exactly how user contributions will work. It's currently
able to link to specific pages (well, xml:ids) and allow additions to
patch queues. Additional testing is needed though with a focus on
resource usage because we can expect many people ending up here (many
just curious and looking) and the online editor can be a resource hog.
Comments to correct/enhance previous user note(s)
One consideration is how we keep track of these referenced notes.
Comments with a link to article/blog post
One trouble we currently face is that some people (for various
reasons) prefer to write "documentation" and post it on their blogs
and then add a link within a manual comment. This is terrible. It
_almost_ makes me want to add a disclaimer on the user notes page that
says "If you post to your blog, in exchange we may steal the content
and add it to the manual." ;) But at the same time it can be useful so
usually we leave the links.
Comments asking for help
Which in my view breaks down to the following functionality:
Report errors:
redirect to bug report (online editor later)?
Request help:
redirect to a 'where to get help' page?
Comment:
Auto tagged with the relevant PHP function/method?
Optional 'code snippet' tag ?
Optional 'hyperlink' tag ?
So I agree with you that the users seem to want a code snippets/tips/
etc repository.
When you take out the error reports and help requests, a code
snippets/tips/etc repository is left.
Not sure about using tags though, I don't quite see what your goal
is with tags. It's cool and all that but what's the benefit, when
comments are linked specifically to a doc on paragraph/section
level? Or are you thinking of accessing comments through a separate
interface as well, without needing to go through the doc pages? That
could be interesting :)
If a comment is simply a code snippet then it's tagged (or
categorized) as such and treated like a code snippet. How exactly we
treat these different tags, like code snippets, I'm not exactly sure
but simply knowing is half the battle. A user may select "show me the
code snippets" and will then see them all. Or choose not to see them.
And we only end up running the syntax highlighter on these particular
notes.
And then there's the case of how difficult it can be for a user to
find the correct place. If a snippet uses two string functions then
how do they choose? Could we recycle and show the same (if it's
considered good) snippet within two different manual pages? How would
we easily track and categorize that? Same applies to every category of
course.
Not sure how we'd end up tracking which notes belong to which
paragraphs, a method that seamlessly understands when content is
added, deleted, and changed. This is a possible deal breaker.
Voting, I agree would be very useful. It should be possible to vote
down a comment also imo, let the negative votes of users tell us
which comments might need attention. And the high scoring comments
will hopefully be the most useful.
One consideration is tracking when one note directly refers to
another, so we'd have some sort of loose threading. But yes, agreed
that the idea here is allowing users to help with QA because currently
the documentation team either deletes or edits notes but this task is
overwhelming and near impossible.
Aha, I now understand how tags could be used. An excellent code
snippet for PHP 5.3 for example could be irrelevant (unavailable)
for PHP 5.2. It would be nice to filter comments by versions, and I
guess if I think about it further I'll find other examples of useful
tags...
Didn't think about version specific uses but that's a good idea.
Granted we don't want someone to add 100 tags for every possible PHP
version but for beginning minor versions it seems worthy.
Regards,
Philip
