Re: Proposal for a comments system

[Shaun McCance <shaunm gnome org>]

On Tue, 2010-04-06 at 07:20 -0500, Paul Cutler wrote:
> On Tue, 2010-04-06 at 10:28 +0100, Phil Bull wrote:
> > Hi Philip,
> > 
> > On Tue, 2010-04-06 at 01:12 +0100, Philip Withnall wrote:
> > [...]
> > > Are there any use cases for the comments system which would produce
> > > comments which wouldn't need to be resolved (in whatever way) by
> > > modifying the documentation? i.e. Are there any types of comments which
> > > should always be visible on a page? If there aren't, the system could
> > > just be a fancy interface to Bugzilla, automatically putting together a
> > > bug report with details of which part of the documentation needs to be
> > > changed.
> > 
> > I think that Shaun is proposing something similar to the "User
> > contributed notes" used by the online PHP documentation [1].
> > 
> > One issue I'd like to pick up on is that people will definitely try to
> > use this feature to ask for support. First of all, we should design the
> > system in a such a way as to discourage this. Then, we'd need an easy
> > way of forwarding support requests to an appropriate mailing
> > list/forum/etc. I guess GNOME could sign up to Launchpad Answers...

Having an answers system would rock. Forums are a poor
substitute. But I don't want to block on that.

> That's my biggest concern - if we get comments we need to do something
> with them.  It's like filing a bug - if the user takes time to go
> through the steps, we owe them something.
> 
> Do we believe we have the bandwidth and process to do this?  Personally,
> I don't know - especially considering the amount of documentation we
> want to re-write (will this take away from writing?)

The essence of writing is planning, and good planning means
knowing what your readers need. We have almost no real data
on that right now. The best thing we have is Phil's script
for scraping IRC. But IRC has a pretty heavy selection bias.

Will it take time away from putting words to paper? Sure.
But looking at user feedback is essential to writing well.

--
Shaun