Re: Excise input methods

[Phil Bull <philbull gmail com>]

Hi Shaun,

On Thu, 2011-03-31 at 13:47 -0400, Shaun McCance wrote:
> I've been struggling with documenting input methods. I have
> a vague notion of how they work, but not enough understanding
> to write really stellar help.
> 
> I was just chatting with Owen, and he informed me we don't
> even have a blessed upstream input method. Fedora uses IBus.
> Some distros might use SCIM. And there's all sorts of overlap
> between the IBus stuff and our keyboard layout selector.
> 
> So if I'm to document input methods, I either need to write
> complete docs for all the various input methods, or I have
> to write crap like "Select an input method. You're on your
> own now."
> 
> What's more, this is all planned to change in 3.2:
> 
> <owen> shaunm: in 3.2 (if we get thngs done), keyboard layouts are
> actually going to be closely integrated with input methods, so the top
> level view is "I want in to write in Greek" vs. "I want to write in
> Japanese" rather than "I want a Greek keyboard layout" vs. "I want a
> Japanese input method"
> 
> So right now, I'm thinking of cutting the page for input
> methods, and removing the section referencing them from
> tips-specialchars. It sucks, because this stuff really
> needs docs in its current state. But it'll take me the
> rest of the week to write something only barely passably
> decent, and then we'll throw it away in six months.
> 
> Objections?

Strong objection :)

Even if we can't write anything wonderfully helpful, we should at least
try to point the user in the right direction. Good help isn't about
making the software look good or ignoring difficult issues, it's about
being useful and honest.

If the honest answer is that "input methods are crappy and a pain in the
arse", then that's what we need to write. Pointing the user to some
external resources that they might just be able to use to get something
working is better than completely removing the topic. So, my advice is
to do the best job you can given the fast-approaching release deadline
and the complexity of the issue, and put that in the help. And don't be
afraid of acknowledging that that help isn't comprehensive right there
in the help topic - as long as the user knows what he/she is getting.

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/~philbull
Book - http://nostarch.com/ubuntu4.htm