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 _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
