“It Doesn’t Work” and the Art of Reporting Bugs

Image via Flickr

“It doesn’t work.”

No phrase is as frustrating, so gut sinking, anger inducing and nerve wracking to a developer than “it doesn’t work.”

This blunt opening line usually signifies the beginning of a long course of troubleshooting that developers dread.

I’ve literally had this conversation several times in my career:

“It doesn’t work.”
“What doesn’t work?”
“IT. The website.”
“Where on the website?”
“I’m not sure. Just fix it.”

To many non-technical people, this seems like a perfectly logical line of reasoning. After all, it’s not this person’s job to test the website, and it’s not his or her job to figure out what’s wrong.

But, by sending a lovingly vague bug report, this person has decided both to take up the responsibility of reporting a bug to be fixed, while simultaneously making the fix for that bug a time consuming mess all at the same time.

Bugs: A Pain In the Butt

Like it or not, bugs are an inevitable part of all software. And many bugs can take hours of trial and error for a developer to narrow down and fix. For an engineer, it’s impossible to deduce what the issue is without spending a good of amount of time talking to the person who reported the issue and tedious attempts to reproduce the problem.  Fixing bugs can take a lot of work.

The vagueness of the “it doesn’t work” report means the issue could be literally anything—the website could be down, the signup screen could be broken, the app could unwittingly be taking naked selfies of the user and e-mailing it to all their friends—there’s just no way of being able to tell.

Surprise! You’re Quality Control

Even with the most rigorous quality assurance (QA) testing, bugs slip through from time to time. For small teams and individual developers, there often isn’t even any formal QA testing at all—making the client, managers or staff partially responsible for at least a portion the QA process.

As a non-technical person working with software developers, you can almost always expect to play the role of QA tester to some degree—whether it’s in your job description or not. It’s in your best interest to accept your new responsibility. When bugs are critical problems impeding business or putting on a bad face for your organization, your help with the bug-finding process is going to help solve it that much faster.

Reporting Bugs – the Right Way

So here’s how to write a bug report that helps narrow down the problem, makes your developers happy, and expedites the process of getting your software to just… work.

An excellent bug report should include:

1) Summary

What is the problem? Summarize it in 10 words or less.

2) Location

Where is the problem? If it’s a website, copy and paste the URL. If it’s not, give the name of the screen you are on.

3) What environment are you using the software in?

Are you on a PC or a Mac? Firefox or Chrome? iPad or iPhone? iOS or Android? What software version(s)? What browser plugins do you have installed? What crazy software are you running in the background?

4) Describe the problem.

Give a detailed description of what happened.

5) List the steps to reproduce the problem.

Describe every step you took to get to the issue you’re having. Example: “1) Open web browser; 2) Go to www.mysite.com; 3) Click on ‘Log in’ button”

6) Expected result, and what actually happened.

Tell them what you expected to happen when you took the steps you listed above, and what actually happened. Example: “Expected result: Log in form appears. Actual result: A picture of a teddy bear appeared with the words, ‘Bear with us, the site is broken.’”

7) Suggested fix

Do you think you know how this should be fixed? Great! Save the engineer some time and confusion and describe how you think it should be fixed here.

8) Screenshots!

If you can see the problem, take a screenshot of it and include it with your bug report. This can sometimes be the single most important thing you can offer up in a bug report. If you can mark up your screenshot to point to the issue, even better. Taking a screenshot depends on the computer or device you’re using. If you can’t figure it out, take a photo of the screen with your phone and send that.

9) Priority

Priority is subjective, and oftentimes to the bug reporter, everything can feel high priority. But be fair, take a deep breath and think about how important the issue really is. It helps to think about it in these terms.

1. Critical: “STOP EVERYTHING AND DO IT RIGHT NOW!!!!”
2. High: “This needs to get fixed ASAP.”
3. Medium: “Fix this soon, but it’s OK if it doesn’t get done right away.”
4. Low: “This can be put off if needed.”
5. Icebox: “This is an idea or suggestion that we should put on ice for later.”

Making Engineers Love You

If you find something wrong—no matter how alarming it seems, stop what you’re doing, take a step back and write a decent bug report.

If your developers have a bug or ticket tracker, you should log it in there, but if you don’t (or can’t figure it out) you can fire up your email or start a text document. If you’re experiencing a lot of bugs, try creating a spreadsheet listing all of them and send that. Don’t just call them up or send a one-liner message. Document your bug before you make the alert, the engineers will use this bug report to prioritize and reference when making your fix.

So now when you check out that shiny new software that your developer(s) released and something—gasp—breaks, you know how to get it fixed faster, more effectively and without frustrating your engineers. You become a helpful part of a team, instead of a clueless outsider and hey, maybe you learned some things to make you a more software-savvy person in the process.

If you’d like to hear some interesting debate about this post from real software engineers, check out some of the discussion on Reddit /r/programming.