Re: admiting to our flaws

[Ryan Paul <gaerdin gmail com>]

Karderio couldn't replicate the Ataxx bug on his own computer, and
mentioned that it could be specific to my distribution. I have noticed
that the screenshot of Ataxx on the GNOME Live wiki (apparently added
yesterday) shows at least one feature that isn't in the version that I
used while writing the documentation. Should I get the latest version
from cvs and update the documentation accordingly as I am rewriting it
in docbook format?

I definitely think that certain kinds of bugs need to be addressed in
documentation. As a user, I get really irritated when I spend half an
hour trying to figure out what I am doing wrong before realizing that a
particular problem relates to a known bug.

That said, I can understand not wanting to include bug information in
documentation. There are already suitable venues available for
articulating those kinds of program deficiencies, and the documentation
can't cover every bug.

I think that it makes sense to include a Known Issues section at the end
of a doc which could describe issues that directly affect documented
functionality specific to the program, particularly in instances where
the fact that its a bug may not be obvious to the user. I think that
Shaun's admonition boxes are a good solution as well.

I'm hoping this gets through to the list... I seem to be having trouble
with it lately.

-- SegPhault

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
> 
> 
> 		
> ___________________________________________________________ 
> All New Yahoo! Mail – Tired of Vi gr@! come-ons? Let our SpamGuard protect you. http://uk.docs.yahoo.com/nowyoucan.html
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list