How to Write Error Log Messages

You know in Star Trek, when they’re looking into the Captain’s Log? I bet they also had an Error Message log for when things went real bad. You know, like when the Klingons actually won and took over the Enterprise.

Ok, so what’s this got to do with tech docs?

Well, it’s a roundabout way to look at error log messages. They don’t get much love, do they?

If you’re not happy with the quality of your error log messages, see if this helps.

Severity Levels

Error messages fall into the following categories: Error, Warning, or Information.

Define your log messages according to their severity.

Error – The error is severe. Immediate action should be taken to avoid the loss or corruption of data.
Warning – Action should be taken at some stage to prevent a severe error occurring in the future.
Info – An informative message, usually describing server activity. No action is necessary.

Checklist using Cause/Solution Format

Use a cause/solution format when writing the error log messages:

For example:

9968: No port defined for import.

Cause:

The server cannot detect a port.

Solution:

Contact Technical Support.

9969: Bulk import not supported.

Cause:

The server will not accept an import.

Solution:

Contact Technical Support.

9807: Ignoring large value for new_attribute_name.

Cause:

The value of the configuration attribute is invalid.

Solution:

Change the value of the configuration attribute. Refer to the Help files for the acceptable value range.

Checklist for Complex Issues

In some cases, you may want to provide more background details and list the steps to resolve the issue.

6696: Source Not Available

Description:

A Source is not available. Last monitoring query showed source is unavailable.

Cause:

The error occurred because of any of the following reasons:

Data source is offline
Data source is not responding
Network issue

Solution:

Do any of the following:

Bring source back up
Fix network issue
Bring source down.

… stay tuned for next week’s episode!

Error Message Guide Template

Download MS Word Error Message Guide Template