TechWhirl Sponsors

About TechWhirl

TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.

For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.

Re: Writing error messages? (longish)

Fabien Vais <phantoms -at- pop -dot- total -dot- net> said:
> A message should do the following:
> 1. Explain in simple, succinct terms what the problem is, WITHOUT
> BLAMING THE USER for having done anything.
>
> 2. Tell the user how to FIX the above problem, or at least how to
> TRY to fix the problem. If there are several things that the user
> can try, ALL these options should be given. If needed, you can
> use the "More info..." button Geoff was referring to.

Right on! No one cares what went wrong. They care what they can
do about it.

> I have often had arguments with programmers about error messages
> that did nothing for the user...

Most bad error messages are actually debug statements. *That's why
programmers like them that way.*

Scenario 1: a van races up to the scene of the crash and two
people leap out. One surveys the scene, calls for backup, orders
some onlookers to divert traffic further up the road. The other
performs triage; sees most of the victims are OK for the moment
but two of them need immediate attention. They start emergency
treatment. An ambulance and police backup arrives...

Scenario 2: a van races up to the scene of the crash and two
people leap out. One, a civil engineer, surveys the scene and
shakes his head. "What a mess. Looks like that tree there
obscured the stop sign and this bozo ran right through the
intersection" he says, prodding a groaning victim with his toe.
His companion, a coroner, is taking notes. "Mind you don't trip
over that stiff," she says. "What the hell is a school bus doing
here this time of day anyway? School doesn't finish for another
hour." There are people lying everywhere, moaning in pain. "Help
me," says one. "You want help!" says the civil engineer. "OK,
here's some advice. NEXT TIME DON'T WALK IN FRONT OF A CAR!"
"I don't know," he says to some onlookers. "Maybe they should
move some smarter people into this neighbourhood." The two of
them jump back in their car and drive off.

Well, I exaggerate *slightly*. But many error messages (and most of
the really bad ones) are like the coroner and the civil engineer,
announcing the immediate cause of the problem and musing privately
on how it could be avoided in future. This is good and necessary
but not while people are lying there in pain.

What's really needed is to send in the paramedics and the police.
Deal with the situation. Comnfort the victimes. Mitigate the
damage. Prevent further harm. Get the traffic moving again.