Re: admiting to our flaws

[Shaun McCance <shaunm gnome org>]

On Tue, 2006-07-11 at 18:11 +0100, Joachim Noreiko wrote:
> The recent rewrite of the Ataxx docs raises a point:
> 
> "When the Animation checkbox is selected, the pieces
> will visually change when captured. The animation is
> different for each tile set. [NOTE: This feature is
> really buggy. When the checkbox isn't selected, the
> program doesn't work and suffers from a wide variety
> of rendering bugs. Should I mention this in the
> documentation?]" 
> (quote from 
> http://live.gnome.org/DocumentationProject/AttaxDocumentation
> )
> 
> I know that the Style Guide says not to make up for
> inadequacies of the software [1], because as I think
> Shaun once put it, the user will shout at the screen
> "Don't tell me it sucks, FIX IT!"
> But... if we gloss over problems and don't acknowledge
> them, the user might shout "How can you seriously
> think this is the right way to design an interface?"
> (I scream this at GIMP every time I use it.)
> 
> There is also the matter that GNOME is not produced in
> the same way as corporate software. We *want* our
> users to become contributors.
> 
> Is there a middle ground?
> If a certain function or component may be buggy, or a
> procedure is tediously complex (adding a way to switch
> keyboard layouts when you've just installed new ones,
> for example, bug 326138), could we signal this to the
> users, and mention (briefly) that GNOME developers are
> working on this but could use help?
> 
> I'd appreciate your thoughts on this. 
> If this is something we think should be done, we could
> perhaps devise a short sentence we can use each time
> that links to the "contributing to gnome" section of
> the user guide.
> 
> [1]
> http://developer.gnome.org/documents/style-guide/fundamentals-3.html
> and
> http://developer.gnome.org/documents/style-guide/usability-non-objectives.html

Joachim, I think this is a very tricky issue, and there's
no single right answer.  But I do believe that, if the user
is likely to encounter a problem, then it is our job to let
him know about the problem, and tell him what he can do.

Here's the way I look at the "making up for inadequacies"
thing: The greater Gnome community should not tolerate bugs
simply because they are documented with work-arounds.  That
would be using the documentation as a crutch for bad software.

Here's an idea that just popped in my head.  We have those
admonition boxes like caution and info.  Perhaps we could
have one for bugs.  I think bug warnings are best put into
admonition boxes anyway, so why not have one just for bugs?
Then every bug admonition could be linked to the bug report
(DO NOT put in a bug admonition without filing a bug), and
users could clicky clicky over to bugzilla.

Bugzilla will always contain more detailed and more current
information about the bugs than we could maintain inside the
documentation.  Plus, it shows people our open development
process, and encourages them to join the fun.

Thoughts?

--
Shaun