Code Leader: Using People, Tools, and Processes to Build Successful Software

11.5. Making Messages Actionable

After making tracing easy to configure, the second most important thing that you can do to make logging more useful to support personnel is to make sure that all of your trace messages (or at least those intended for non-developers) are actionable. In most cases, if a developer writes code to generate a trace message, he knows why that message needs to be written. Something caused the event that generated the message, and most of the time the developer doing the writing has a pretty good idea of not only what that event is, but why it occurred.

It is vitally important to make sure that any error message you report to the end user, or especially to support personnel, contains information on what happened, why, and what to do about it. There is no use reporting an error to operations if they can't tell what actually went wrong. If they have to look up what to do about it in a manual somewhere, they're wasting valuable time and energy that could be better spent on fixing the problem.

The worst case is showing a customer an error that only makes sense to a developer:

TcpException in MyApp.Network.dll, MessageSender.cs line 42.

This does not help the operations center at all. This kind of message results in the customers calling your support center, which makes them unhappy and costs you money. It is slightly better to keep the technical details out of it:

Failed to send message to banking server.

While this spares the operations folk the technical ...