How do you document error messages?

[Geoff Hart <ghart -at- videotron -dot- ca>]

Mary wonders: <<Our organization desperately needs to provide our users 
& support staff with more info about the error messages that our 
various products produce.>>

Is that _your_ perception, or the organization's perception? If the 
former, you've got a much tougher job because you must persuade 
everyone that your perception is correct. If the latter, you can enlist 
the aid of someone with authority (the development manager ideally) to 
insist that things be done better.

<<Currently, our error messages display with vague descriptions written 
by our developers. We're hoping to add more meaningful content to each 
error message...>>

There's a category of errors described as "we've demonstrated 
mathematically that this cannot happen" or "we have no idea why this 
happens". There's little you can do about these other than to encourage 
developers to provide an easy means of communicating the problem to the 
developers so they can try to fix the problem. Mac OS X has a lovely 
feature such that whenever an application crashes, the operating system 
presents a snapshot of the current state of memory and a button "Report 
the problem" that lets you send it to Apple for investigation. I 
believe Windows has something similar?

For all other errors, the developer should either know the cause of the 
problem (e.g., you typed a number where the software expected a letter) 
or have a very good idea about it. The developer should be documenting 
this logic directly within the code that generates the error message 
(otherwise, no future developer can easily figure out the logic when it 
comes time to maintain the code, leading to maintenance nightmares). If 
the documentation is lacking, the development manager must fix the 
situation pronto.

Based on the documentation for each error, it's usually possible 
(sometimes with the developer's help) to understand and explain the 
problem. At a minimum, the error should be numbered in such a way that 
the developer (and tech support!) can track down the problem. For 
example: "Error 13: A buffer overflow occurred in module A of 
SoftwareName. This is not something you can fix. Please report the 
problem to MicroBugs."

For errors with known causes and solutions, the solution is simpler: 
Explain the problem, then offer the likely solution. "You entered a 
number, but only letters can be used in this field. Please try again, 
using only letters, or click the [?] icon for more information on what 
you can type in this field."

<<... as well as to the Help systems & other docs.>>

To the extent that it's possible, an error message should be 
self-documenting or (as noted above) take the reader directly to an 
online solution. Readers should never have to search to find out what 
it means. Because this isn't always possible, the error message should 
at least have a clear hook to an appropriate explanation; for example, 
if the error is numbered, readers (and support staff!) can search for 
"error number 12354" in your knowledge base.

<<One difficulty we have is how to identify the error messages (not all 
of our products generate a list of messages).>>

In the software I've worked on, the error messages are stored in one of 
two ways: either directly in the code, right where the error condition 
occurs ("If error, then display message 'an error occurred' here") or 
in an external "resource" file containing all the error messages, 
numbered in such a way that when the code is compiled, the correct 
error message is linked to each chunk of code that could generate an 
error message. The latter is basically identical to using context IDs 
for online help: the developer enters a number in each chunk of code, 
and that number is then linked to a specific help topic.

It is trivially easy to identify error messages, but the developer must 
be willing to do it--or must be forced to do it by their manager. All 
you do is create a simple coding system: either "get the next available 
error number from a list shared by all developers", or code the error 
semantically so that it's self-documenting. For example, programmers 
would probably love a system in which each error would be named based 
on the name of the module, the specific routine in the module, and the 
type of problem: PrintNumberofcopiesNumbertoolarge = error in the print 
module, in the "number of copies" field, and occurred because the user 
typed a number larger than the maximum for this field.

<<So far, this has been a documentation-only task for us. We have 
extremely limited resources & simply don't have access to the 
information we need.>>

This isn't something you can do without support from the developers. If 
you can't get that support, do triage (prioritize your efforts): spend 
time on only the most crucial things (the ones with the most dire 
consequences or with the biggest payback).

--Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l 

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