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.
Catheryn Mason is seeking <<... advice on writing error messages that are
concise, helpful, and not intimidating to the user... Anything, as a user of
software applications, that you either really like or hate to see in an
error message?>>
The worst error message I've ever encountered is also the most common one:
the dread "Abort, retry, fail?" from DOS. This fails to meet just about all
the possible criteria for a good error message:
- it doesn't clearly explain the problem that occurred
- it uses words that are either synonymous (abort = fail?) or that are mere
placebos (I don't recall "retry" ever working)
- it provides no information on what you can do about the problem
- it provides no bug-tracking information that tech. support or the
developers can use to figure out where the problem occurred and what they
can do about fixing it in subsequent software releases.
A good error message should clearly explain the problem (e.g., "there
appears to be no diskette in the A drive"), should use words that mean
something to the reader (e.g., "You have two options: Cancel or Try again"),
should explain what to do about the problem (e.g., "Insert a diskette and
click the button labeled Try again"), and should provide a clue to the
support staff (e.g., at the bottom of the dialog box, "Error code = Disk
error 27"). The latter is moderately more work for the developers, since
they actually have to think about tracking errors rather than just using a
one-size-fits-all error message for every possible error (e.g., "an error
occurred... try again"), but it's not rocket science and it's not all that
time-consuming. It has the offsetting advantage that the support staff can
look up the error code in a tracking database to determine how frequent the
problem is (thus, how important it is to fix) and what the most common
workable solutions have been.
<<I seem to veer between two extremes -- one is a "just the facts, ma'am"
minimalist approach (as in "System date and time could not be reset"), the
other is loading the user down with way too much feedback and including
information in the error message that might belong appropriately in a pop-up
box or a help file>>
First, you're working with the wrong understanding of "minimalism".
Minimalism does not mean writing as little text as grammatically possible;
it means providing all the information that the user needs to understand
what's going on and respond, and nothing more than that. Minimalist
information should also be concise, but not at the expense of becoming terse
or telegraphic. Second, there's a misconception that providing additional
detail is necessarily verbose. As in all other forms of techwhirling, you
can provide a concise message at the top of the dialog box, followed by a
blank line, followed by elaboration for those who need it; those who don't
will simply read the first line and proceed on their own. An interesting
compromise (which I've seen here and there) is a "More info." button; the
error message itself is reasonably concise, and those who want or need more
information can click the button to get details.
Hofstadter's Law: The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law.
