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 [EMAIL PROTECTED]@! come-ons? Let our > SpamGuard protect you. http://uk.docs.yahoo.com/nowyoucan.html > _______________________________________________ > gnome-doc-list mailing list > [email protected] > http://mail.gnome.org/mailman/listinfo/gnome-doc-list _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
