On Sun, 2010-04-04 at 16:08 -0500, Shaun McCance wrote: > 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. General-purpose spambots could still operate through library.gnome.org, if we're going to have commenting enabled there. Perhaps a CAPTCHA could be used for the library.gnome.org interface? > 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. Would closed comments still be stored for reference purposes (like closed bug reports)? Probably also need a status for "duplicate". > 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. What's the purpose of having per-language, translated comments? As I understand it, comments as you are proposing them are basically mini bug-reports about the documentation, and are all meant to be resolved through updates/extensions/improvements to the documentation. If that's the case, why would the comments need translating? Philip > 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. Could we have some more detail on these ideas for page view statistics? Should there be a way for people to opt out of their usage of help pages being logged? (Don't know why anyone would, but it should be considered.) Regards, Philip
Attachment:
signature.asc
Description: This is a digitally signed message part