Teaching Your Users How To Report a Bug
Test and Monitor | Posted March 04, 2011

Because a user saying, “The software doesn’t work right” probably isn’t good enough to help you fix a software defect. And telling the judge, “Your honor, that’s when I shot him” is unlikely to be considered mitigating circumstances.

For software developers, one of the most frustrating aspects of dealing with users is when the user reports a problem, but doesn’t give you all the information you need. You know the routine: A user submits a bug report that says, “The program didn’t work.” Or, “I got this weird error message and it quit.” And that’s it. No other information regarding what the user was doing, the steps taken to get there, or the precise error message that occurred.

Nevertheless, the user expects you—the programmer or QA engineer—to offer up a solution immediately. If the software is in-house development and the users work for the same company you do, you may have to see that person on a daily basis. Worse, you might hear from him or her hourly, demanding to know why the problem isn’t fixed yet. There will likely be anger, and maybe even a few choice words that aren’t appropriate for this community.

But it need not be this way. Clearly the big obstacle is that the user didn’t give you enough information. How, then, do you get past this situation? The first and most important way is to prevent the situation from occurring altogether by training the user how to be a Good User.

Bugs happen. They’re a fact of life. As much as we try to build perfect software that never fails, truth and experience tell us otherwise. We can work hard to minimize the bugs, and we can use tools to help us catch them before the product ships, but some still manage to sneak through. So how do you prepare your users for the bugs?

To find out, I spoke with Don Rorabaugh, a senior software engineer based in Atlanta with over 25 years of experience. Rorabaugh has worked for several large companies, including one of the biggest telecom companies, and has headed up teams that have developed both commercial software and in-house software. He had plenty to say. First, he says, focus on a certain psychology: your own, not the users’. Nobody wants to ship software that’s imperfect. Why would we want to tell our users that the software we’re giving them is broken? But we don’t have to. Think of when you buy a brand new car. The salesperson isn’t about to tell you that the car is going to break down. But the salesperson does say that if anything goes wrong, please bring it to the service center right there at the dealership. Sure, the service center is usually in back, but there’s always a clear, obvious sign out front. The dealership isn’t hiding the fact that cars do break down.

That’s something we, as software developers, can learn from, says Rorabaugh. Developers need to point out to the users up front that if anything goes wrong, here are the steps to take to handle the situation. We don’t have to tell the users that the software will break; after all, when you buy a car, the dealer doesn’t say that the car is certain to break down (even though it will eventually, probably 10 minutes after the warrantee is over). But we can make sure that our software’s users are aware of the steps to take if something happens. And to make it clear that we’re there for them, willing to help.

To create Good Users, then, we need to teach them two things before the bugs occur: First, how to react to a bug or problem, and second, how to convey the information to us.

The correct reaction to the problem is vital. Users tend to really freak out when something goes wrong. (I know I do!) But instead of just getting mad and shutting off the computer and sending you angry e-mail messages, the user needs to immediately make a mental note of the steps that led up to the problem: What screen was he on? What did he click or type? If you wait a day—or even a few hours—to get this information from the user, most likely he won’t remember exactly what happened and will give you incorrect information. That’s why you want to prepare your users up front for noting what went wrong.

Fortunately, times have changed from, say, 15 years ago, when people would get terrified if something went wrong. Back then they would shut the computer off and refuse to ever touch it again. I would argue that training users to record their steps is easier than it used to be. Today’s users have seen plenty of problems, and they’re in a better mental state when problems occur than were the users of the past. Today’s users realize that their computer isn’t psychically tied to the country’s military arsenal and isn’t going to cause a nuclear launch; nor will it explode and cause the house to burn down. (I’m not making these up; 20 years ago I heard people say these things.)

Don’t be afraid, then, to work with your users and explain that if something ever goes wrong, to stay calm and to note exactly what they were doing at the time. You need to know what screen or form they were on; exactly what steps they took to get to that form; what they typed; and so on. (Of course, these steps differ based on your particular software.)

And probably most important of all, make it clear to your users that you want to know about the problems so that you can fix them. Sometimes our egos get in the way, but the truth is, we work for these people. (If they didn’t use our software, we wouldn’t need to be creating it, and we wouldn’t have a job.) And they love to hear: “If anything goes wrong, please tell me so I can fix it so I can make this software help you do your job as easily as possible.”

I then asked Rorabaugh about the process to communicate this information, such as through a bug database, and he told me I’m jumping ahead of the game. Don’t leave this step yet. Here’s the deal: At this point, people aren’t yet ready to enter in their information into a bug database. Why? Because if they try to fill in a formal form, it’s very possible they’ll describe the steps wrong that led to the problem. Instead, Rorabaugh says, when they encounter a problem, tell the users to grab a sheet of paper and write down what happened, just to help themselves remember. And this is where there’s more psychology involved. The users know that nobody else will see this sheet of paper, and they know it doesn’t have to be formal.

Only then, after they’ve written down the steps, are they ready to fill out the online bug form.

Finally, the technology tools that we developers and QA folks prefer to think about: the online bug form users need to fill out. Based on my own 20 years of experience in software development, I know that these bug forms are typically a huge bottleneck. All too often, the internal bug reporting apps are a disaster. They’re filled with a gazillion dropdowns and textboxes. Users have to be trained for hours on how to use them, and then they won’t touch the application until they really need it. That’s when they can get overwhelmed (because they’re already overwhelmed and cranky about the problem they just encountered).

When designing a form for your users to submit their bugs, give them a way to enter all the required information, and nothing more. Is it really necessary to know exactly which service patch of Windows they’re using? Or is just “Windows” good enough? That all depends, of course, on your software. Maybe your software calls into some unique APIs that may be different for different versions of the operating system. If so, then include that in the bug form. But if not, then definitely do not include it. And do you need Linux in the choice of operating system if your software doesn’t even run on Linux?

Don’t make the user enter in any unnecessary information, because when they do, they may spend so much time on that extra information that they don’t give you the actual information you need. So keep the bug form simple. And about that “severity” field? Leave it off the form unless there’s a compelling reason to do so. Almost every user will consider every bug to be of the highest severity, and once you look at it, you’re probably going to change it anyway. So why even put it on there? There may be situations where you need it (such as if your users are pretty savvy or are stakeholders and truly understand what bugs are more or less severe then others). But if not, leave it off.

“Remind your users you’re working with them, and you’re on their side,” says Rorabaugh. “Remind them that you want to help them do their job, and that you’ll do what it takes to make their job efficient. If you tell them that up front, they’ll be much more willing to give you the information you need to fix the problems. And then you’ll be able to fix the problems quickly, and they’ll be even happier.”

Sounds like a great plan to me. Thinking back over the conversation, it almost seems all too deceptively simple. Give the users a way to remember the steps taken. Provide a simple entry form for them to enter their problem, without forcing them to put in a bunch of unnecessary information. And remind them that you’re doing this for them—even if, in fact, you’re doing it for yourself so that you don’t have to deal with users who are freaking out. That’s certainly a win-win situation!

What practices have you encountered that really helped to train users how to report a bug? Share them in the comments.


By submitting this form, you agree to our
Terms of Use and Privacy Policy

Thanks for Subscribing

Keep an eye on your inbox for more great content.

Continue Reading

Add a little SmartBear to your life

Stay on top of your Software game with the latest developer tips, best practices and news, delivered straight to your inbox