Re: admiting to our flaws

[Don Scorgie <DonScorgie Blueyonder co uk>]

Hey,

To wade in on this (if it ever reaches the list):

I'd be in favour of a "Known Issues" section of docs in need of it.
Perhaps adding a standard template type thing like:
"Although we try and provide high-quality software, issues do arise at
times.  This is the nature of software.  Shit breaks in unexpected ways
sometimes.  GNOME is constantly evolving and these issues may be fixed
in later releases.  We are constantly trying to improve the quality of
software blah blah.  You can help out by <reporting bugs | helping write
stuff | bribing developers>.

Issues know in <foo> and possible workarounds are:
* Foo doesn't start.  A workaround for this is to type <foo> from a
terminal. <link to bugzilla>
* Currently foo makes it difficult to ..."

If needed, a footnote could be put in at the appropriate part of the
guide linking to this section.  This way, it doesn't break the flow of
the doc, but still allows people to know we know about the problem.

Don

On Wed, 2006-07-12 at 12:57 +0100, Joachim Noreiko wrote:
> --- Calum Benson <Calum Benson Sun COM> wrote:
> 
> > 
> > On 11 Jul 2006, at 18:11, Joachim Noreiko wrote:
> > 
> > > 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.
> > 
> > I don't think I'd like to see "this bit doesn't work
> > very well"  
> > explanations in the middle of the user guide, but I
> > guess you could  
> > always take the manpage approach and have a "known
> > issues" section at  
> > the end.  Then you could even just remove that
> > section altogether for  
> > stable releases, because apps aren't "stable" if
> > they have any bugs  
> > that are so bad that you have to mention them in the
> > user guide,  
> > right? :)
> 
> Um, yeah...
> If we actually followed that, a lot of GNOME apps
> wouldn't get released.
> 
> Let's take bug 326138 and be more concrete.
> 
> The user guide should explain how to add a keyboard
> indicator in the help section for the keyboard
> preferencces, because that's where you're logically
> going to look. ("I've added a second layout... but
> wait! How do I switch between them?")
> I simply don't feel comfortable givin a matter-of-fact
> explanation. It's labortiously complex, and I can just
> imagine the user reading my docs and saying "WHAT? I
> have to follow ALL these steps? That's insane!"
> 
> So I have three options:
> 
> 1. Don't write the docs. This hurts the user.
> 2. Write the docs and gloss over the shortcomings. I
> don't like this. I joined the docs team to docs. If I
> wanted to write spin, I'd go into PR or advertising.
> 3. I add a note, at the bottom of the section (the
> bottom of the entire document is pages and pages away)
> to say that we're aware this isn't optimal, and are
> working on improvements.
> 
> Oh and 4. Let someone else write that bit of the docs,
> which a) probably won't happen and b) is just a bit
> lame.
> 
> I know this could be seen as passing the buck to the
> developers (though that's where it belongs) and trying
> to shame them into doing something. That isn't my
> intention. I just don't like writing docs for
> something that's broken. I know how annoyed I get at
> documentation that glibly asks me to press six keys at
> once while wiggling the mouse in a certain way and
> humming The Marseillaise, just to accomplish a simple
> task, and I don't want to be responsible for more of
> that sort of thing existing.
> 
> 
> 		
> ___________________________________________________________ 
> Try the all-new Yahoo! Mail. "The New Version is radically easier to use" – The Wall Street Journal 
> 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