How not to write software help

[ewx]

More and more computers seems to be black. I approve, on aesthetic and historical grounds.

Setting up LNR's new computer last night went fairly smoothly though I did run into a small wrinkle.

One of the installation screens asks you want kind of keyboard you have. Among the bewildering array of options are 'United Kingdom' and 'United Kingdom extended'. So, which did she have? The keyboard had neither description printed anywhere on it, nor did the box it came in. Obviously I hit the help button, which was very good at using animated arrows to tell me which menu the list of keyboards was in but did not describe how to discover what kind of keyboard you actually had.

This has been a running sore in the computer world, actually. X11's configuration often names keyboards for the number of keys; all well and good, but do they really expect you to count the keys on the keyboard to find out how many it has (given that the numbers are typically just over 100)?

Obviously diagrams would help, and doubtless there are plenty on the web (though the MS site which claimed to have them that I tried from my Mac didn't work in Firefox or Safari) but no matter how good they are, unless you have an already-working computer they're going to be of rather limited usefulness. Would it really have hurt to include diagrams in the installer?For that matter you'd have thought that the transition to USB would be the ideal point at which to make keyboards plug-and-play. But, apparently this didn't occur to anyone, or if it did then nobody's taking advantage of it.

Comments

[pjc50.livejournal.com]

The "USB HID Usage Tables" (via http://www.usb.org/developers/hidpage/) specifically defines (a) the mapping of function ID to keys and (b) that keyboards may be modified for different languages "simply by printing different keycaps" to keep the costs down. Grr.

[pjc50.livejournal.com]

After a little thought, surely the foolproof way to fix this is via some program that uses a dichotomous tree to determine what keyboard you have by asking you to press keys, like those old joystick calibration programs for the insane 1-bit PC analog joysticks. Unfortunately the situation has been made worse by the proliferation of "multimedia" keys. My brother has a keyboard where the normal F-keys have been given daft functions and you have to turn on F-lock in order to get the normal behaviour.

[ewx.livejournal.com]

Excellent idea!

[senji.livejournal.com]

Isn't this exactly what Ubuntu does?

[reddragdiva]

It can. However, it annoyingly doesn't have any Mac keyboards. Not even in the PowerPC edition.

[aardvark179.livejournal.com]

I think that's what OS X does if you plug in a keyboard it can't properly identify. It starts by asking you to hit the key to the right of the left shift key. I don't know what it does after that as the only device I've got that triggered this was in fact a joypad with a broken HID description.

[fanf]

After that it asks you for the key to the left of the right shift key.

[ewx.livejournal.com]

I think they could have both satisfied me and kept the costs down, in fact. Almost everyone probably knows whether they have a UK or German keyboard, but not whether their keyboard is 'extended', and the latter probably does need different electronics from the unextended one.

[ewx.livejournal.com]

Yes, it's Windows XP. I think if anything that explanation makes the feeble help text even more annoying l-)

[mtbc100.livejournal.com]

Black ones show up dust nicely.