Whenever we roll out a new system to a client, there are two kinds of training we need to perform to get them up to speed. The first is what you would expect, the basics of how to operate their brand new software; but the second kind might not seem so obvious: how to report a bug.

To start, I’m going to tell you how much we in the consulting business dislike the word “bug.” We dislike it because it’s overused, misused, and used to point fingers. We prefer the word “issues,” because it covers a broader range of possibilities. Maybe it’s a bug, but maybe it’s a feature request, or a training issue, or something altogether different from an error in the code itself. Our job is to evaluate what’s happening and come up with a solution for it. Your job, as an end user of the software, is to make sure we understand what it is that is prompting you to contact us. After all, we are all on the same team, with the same goals.

Here are the four things that you can pay attention to and relate to us, so that we have all the information we need to present a solution as quickly as possible.

1. Where were you?

One of the main things we need to know is context – what part of the system were you in? The Contacts module, the Orders module, etc. Bonus points if you can tell us exactly which screen it was, or better yet, give us a screen capture of what you are looking at. Sometimes, you are on a specific tab as well, so anything you can do to help us understand where to look for the problem is helpful. This also applies to a particular record. If the issue occurred when you were editing a certain contact or order, we would love to know that for our own forensics.

2. What did you do?

Did you click a button, type in a field, select something from a pop-up menu? If so, which one? If the thing you did was part of a larger process, did part of it seem to work normally before something went wrong? Sometimes it’s hard to recall details like this, especially when you are trying to get work done. It’s a good idea to start with some written notes immediately after the problem occurs, or take a screen capture if there is something there to see. Memory fades when you might perform another hundred mouse clicks before you get around to reporting the issue.

3. What did you expect to happen?

You know that something went wrong. That’s because you expected one thing, and got another. It’s important for us to know what you thought was going to happen, because sometimes what you expect and what we thought you wanted are two different things. This might be a failure of the original specification, or an incorrect expectation on the user’s part. Either way, we need to know what you thought was supposed to happen in order to correctly assess the problem. This can also include things like getting an incorrect sum when a column of numbers are added up; if your calculator and the result on the screen don’t agree, you can let us know that you expected a certain result.

4. What happened instead?

Again, details really matter here. If you got an error message, it’s a good idea to write it down or screen capture it before you dismiss the message. This will go a long way in finding the problem. If there was a specific series of events that occurred, we want to know about it. Sometimes, there’s none of the above – just an incorrect result. That’s fine, just let us know what you saw in place of the correct one.

There’s one more thing you can do: don’t try to fix data that is wrong due to an issue, unless it’s absolutely necessary. The first thing we do when an issue is reported, is to verify that it really did happen. Don’t get me wrong, we completely trust our users to give us accurate information; it’s just that the scientific method requires that we verify that there really is a problem to be solved, and that it looks as described. Upon occasion, I have seen an issue turn out to be far more significant that the user realized, just by looking at what they have described. If you simply must correct the erroneous data, please let us know so we don’t waste time chasing ghosts.

As you can surmise from all of this, we in the consulting business have to put on our deer-stalker hats and break out the magnifying glasses to find the answers to issues you report. The more you can tell us, the better!