Use Clear, Consistent Messages

An error message isn't helpful if the user doesn't understand it. What kind of error messages can the user understand? Of course, this depends upon the user. Consider common programming terms like syntax error, integer, Boolean, reboot, and contiguous. If you are developing software for programmers, these terms are appropriate for error messages. If your software isn't for programmers, terms like these are totally inappropriate for an error message. Stop for a minute and consider what it would be like to be a first-time computer user and receive an error message telling you to reboot your computer. Reboot? Do computers have boots? And if they do, how exactly do you reboot it? You must do your best to make sure that the words you use are in the user's vocabulary.

Consistency is important. Make sure that the terminology used in the error message matches the terminology used elsewhere in the program. If the terminology doesn't match, it will definitely confuse the user.

I realize that coming up with a clear, consistent error message while you are in the middle of programming isn't easy to do. It's tempting to write a quick-and-dirty error message and move on. Nonetheless, I strongly recommend that you make an effort to write the best error messages you can while you are programming. If for any reason the error message isn't good, tag it and come back to it later. The visibility of your tagging scheme should depend upon how structured your development process is. For example, you could tag messages that need improving with text such as [Bad message—improve later!], but this technique isn't such a good idea if there's a chance you might ship the program with those tags. In this case, a safer approach might be to tag such error messages by appending a tab character to the end of the string. Using this method, the tag isn't visible to the user and at an appropriate time, you or another team member can review the tagged messages and improve them. Ideally, your technical support staff and technical writers should review all the error messages as well.