Proposal for a comments system

[Shaun McCance <shaunm gnome org>]

Hi folks,

We've talked before about having a system to allow users to
comment on help pages. I attended a session about this last
week at the WritersUA conference. I think we're in a pretty
good position to do this with Mallard. Here's my proposal.
I'm trying to keep it as simple as possible.

We create a server that stores comments and allows users to
submit comments. This will be a simple web application, but
it won't have a public-facing web interface. It is designed
to be used through Yelp or library.gnome.org.

Comments are submitted over HTTP. They contain a person's
name, an optional email address (not published), and the
text of the comment. Comment text is restricted to plain
text with a character-count cutoff (~300ish characters).

To reduce spam, we can require a particular User-Agent in
the HTTP request. This won't stop anyone who wants to spam
our system specifically, but it will block general-purpose
spambots.

People with accounts will be able to log into the comments
server with a web application. They will be able to close
comments with a status like "resolved", "invalid", "spam",
or "troll". Closed comments won't appear anymore. I don't
think we need to be stingy about giving out accounts. If
we could somehow tie it to git accounts, that would make
life easier for us.

Comments are per-page, and also per-language. Translators
will be able to translate comments into English. These will
be tied together on the server, so that when we close the
translated-into-English comment, the original is closed as
well.

There are a number of benefits to doing this. We get real
user feedback on what we're writing. That's huge. Because
Yelp will have to ask the server for the comments for each
page, we also get some metrics on which pages are visited
most. And people tend to use things more when they're
directly engaged.

-- 
Shaun McCance
http://syllogist.net/