Re: admiting to our flaws

[Joachim Noreiko <jnoreiko yahoo com>]

--- 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