Re-post: Error messages: text for the title bar?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

David Rapport reports: <<I have been doing a little Web research into the
art of writing error messages. The consensus seems to be that they should
include a statement of the problem, the cause and how the the user can solve
the problem. All in the most concise and informative way possible.>>

That's the theory, but it can be a challenge getting the programmers to
address the latter part. My experience has more commonly been that they
respond "we don't know what might cause this problem, so how can we tell
them how to solve it?" I can usually get them to accept a few suggestions
for the most common causes of the problems, but doing a better job often
involves deeper reworking of the program logic to make it clear when the
error occurred (thus, why it occurred). That's rarely possible.

<<what should be included in the title bar of the message?>>

Contextual information that you then don't need to repeat in the body of the
message. For example, if the problem is "Word cannot find the printer you
specified", that should be the message title. You can then start the error
message itself as follows (for example): "To connect to your printer,
confirm that: 1. the printer is turned on, 2. the printer cable is
connected, etc."

<<I would like to suggest the following guidelines for title bars in error
messages... 1. A brief description of the remedy.>>

Probably not a good choice in most situations. You need to explain the
problem before you explain how to solve it, and the title of the dialog box
won't have room for this much additional text.

<<2. A brief description of the error/problem. >>

That should be the first choice, as explained above. Just make sure you
relate the context to the user's task using words that relate well enough to
the software interface that readers can see the connection between their
task and the interface.

<<3. A description of the context within the application (eg Printing,
Saving).>>

That follows inevitably from the previous suggestion, which focuses on the
task, and thus probably doesn't need to be a separate choice.

<<4. The name of the dialog box that appeared prior to the error. (Sometimes
this will be the same as 3.)>>

Probably not. In all likelihood, the dialog box is either still open (so why
repeat its name?), or if it's closed, the reader won't remember the name of
the dialog box anyway (that's software logic, not user-focused logic).
They'll far more likely remember the name of the task they were doing, so
that's what you should use.

<<5. The application name. This would be a default for all messages, if
nothing else is appropriate.>>

I think this should be part of the message title (the dialog box) in all
cases. It used to be that this was unnecessary because people would only run
one program at a time, but nowadays having multiple programs open suggests
that an error message lacking a referrant will be mysterious: which of my
five programs caused the problem?

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada 

"I have always wished that my computer would be as easy to use as my
telephone. My wish has come true. I no longer know how to use my
telephone."--Bjarne Stronstrup (originator of C++ programming language)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A new book on Single Sourcing has been released by William Andrew
Publishing: _Single Sourcing: Building Modular Documentation_
is now available at: http://www.williamandrew.com/titles/1491.html.

Help Authoring Seminar 2003, coming soon to a city near you! Attend this
educational and affordable one-day seminar covering existing and emerging
trends in Help authoring technology. See http://www.ehelp.com/techwr-l2.

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.