Re: admiting to our flaws

["Murray Cumming" <murrayc murrayc com>]

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

I think you are exaggerating. It would be nice for this to happen
automatically but it's not insanely difficult if that doesn't happen.
Documentation can help with this in the meantime, and it's the likely
place for people to look (or google to) if they want to know how to do
this.

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

Just saying how to achieve something is not glossing over it. You don't
have to pretend that it's perfect. Just say "This does not yet happen
automatically." right there in the text.

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

!perfect != broken.

Documentation writers must deal with the real world, while politely filing
bugs to make the real world better.

[snip]

Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com