Documentation vs. the interface?

[Geoff hart <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Christine Pellar-Kosbar reported <<A friend of mine has recently been asked
by management for his thoughts on what the next priorities should be for
documentation.  His thoughts are that the documentation would be far more
useful if the product had a useful interface.>>

That's pretty much a truism: you can't fix an incompetent interface by
documenting it. All you can do is produce convoluted, difficult
documentation.

<<My friend feels there should be some assistance to the user, if not menus
and prompts, something that is quicker than searching through the
documentation --some sort of context-sensitive help.>>

One really good strategy (since it involves minimal reprogramming and is
thus easier to sell to the developers) would be to build "affordances" into
the interface. For example, rather than simply having a "mailing address"
screen with five blank fields and no clues, you'd add the words "First and
last name" beside the first field, "street address" beside the second field,
and so on. That's a trivial example, but you can make the affordances
progressively more sophisticated: for a date field, the affordance might be
something like "(yyyy-mm-dd)", to inform the user that dates should be
formatted as four numbers followed by a dash followed by... etc. With a
little thought, you can develop surprisingly sophisticated cues that rely
solely on the textual labels beside the fields, and that take little space,
particularly if you know the kind of data-entry conventions your audience is
familiar with. Context-sensitive help is the next step: with a cursor in any
field, pressing F1 or clicking the Help button for the object (dialog box,
window, menu, etc.) that's open should instantly summon help for that
object. Ideally, there should also be easy links to the help for the broader
context; for example, if the help is for a single field in a dialog box, the
user should easily be able to scroll up or click a link to see help for the
dialog box as a whole.

Here's a slightly heretical opinion: forcing a user to resort to online help
means that the user interface is a failure. Yes, that's an overly strong
statement and somewhat unrealistic given current technology and the fact
that audiences vary so widely in their preferences and skills. But if you
aim for this holy grail of interface design, then even when you don't reach
that target, you still vastly reduce the amount of help you need to write,
and thus, the number of users who must resort to using it.

<<management wonders if experienced programmers would want this sort of
assistance.  After all, the management reasons, they are used to
programming.>>

If the management "wonders", then you're in luck: they haven't already made
their decision. Thus, they should be willing to let you ask the programmers
rather than just making assumptions. That's a really good thing to do, and
the results will support and guide your strategy much more strongly than
just reporting your own assumptions. Heck, maybe the current audience really
doesn't need affordances or online help... but I wouldn't bet on it. More
likely by far, they simply need a different form of help from other
audiences.

--Geoff Hart, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca 
"The paperless office will arrive when the paperless toilet
arrives."--Matthew Stevens