10 Things You Should Know When Submitting a Bug

An on-call technical support engineer wakes up groggily at 2am, when his phone rings. It’s a department manager. “Huhhhh? Huhhlllo?” he mumbles into the phone.

“Your software doesn’t work!” states the angry voice on the other end.
“Uhhh… Could you be more explicit, sir?” asks the still bewildered techy, trying to figure out what’s going on.
“Your software doesn’t #&@<ing work!”

So, that might sound like a joke, but for many people in the software development business, this is just another workday. It seems that whenever somebody has a technical issue, they become even more technically illiterate than they might normally be. Personally, I believe that fear and frustration with their unknown situation, coupled with annoyance at having to deal with a less-than-perfect product reduces the end-user’s ability – perhaps at a subconscious level, perhaps not – to be a part of solving the issue. They want it solved, and they don’t care how.

We want information. INFORMATION!

No, I’m not the new number two. I’m just another developer, who has to solve problems with software, and consequentially, solve problems in the software that solves the problems. I get bug reports coming from end users, testers, middle managers – sometimes even fellow developers – that leave me without anything more than a general sense that there was a disturbance in the force, and the software is not performing within acceptable parameters.

Please understand! Most of us are actually eager to solve problems! A lot of us actually got into this business because we have a hacker mentality, we’re tinkers at heart, and we view every problem as a challenge to meet! Don’t hear us clicking away furiously at our keyboards, guzzling coffee, muttering curse words (often in foreign languages such as Russian or Klingon), and then stop with a resounding “WHOOP!” of joy? That’s a feature we developed or a bug we fixed.

Help us help you.

The items below are the top ten things every developer wants you to provide – as best you can – to help him or her understand what the problem is and how to reproduce the issue:

1 – What do you mean to say?

I know that for many of you, the official language might not be your native one. Where I live, roughly half of the people are foreign-born (which is great, by the way – I like diversity). It’s fine. But please, please, do your best to write your bug report in a precise, understandable manner:

• Be specific – did you load a file? Fine. Did you click on a button, select from a menu, or did you use a keyboard shortcut? It might be important. For bonus points, try all different ways to do whatever you did. If it works one way and not the other, let the developer know.
• Be explicit… as in precise. Instead of the ‘it’ pronoun, describe it (‘the window’, the ‘message box’ the ‘radio button’, the ‘phone’, etc. Just not ‘it’).  Use the Find command in your email client, browser, MS Word, or whatever you’re using to report the bug, search for the word ‘it’ and replace it.
  Also, avoid ‘they’, ‘he’, or ‘she’ unless there can be absolutely no doubt about the person’s identity.
• Reread what you wrote – unless you’re completely incompetent as a writer in the language in which you’re writing (and I guess it’s okay, if they hired you despite your language deficiency), you should be able to see if you think that you were clear. If you weren’t, please correct your grammar. And for the love of your chosen deity, please use a spellchecker. Correct those squiggly red lines!

2 – Can I please have a bug report, hold the attitude?

Jokes aside, we usually do not insert bugs into the system intentionally. At best it was the one defect that slipped the developers’ scrutiny. Often it is the product of being rushed to meet a tight deadline. At worst it is the result of negligent work born of the despair of either not knowing how to work properly and worse – knowing how things should be done, but not being able to do them the right way (see aforementioned deadline).

Either the poor developer is mortified by the bug (extreme unhealthy reaction – but it happens), or the developer has become apathetic to the bug through continual disillusionment (extreme unhealthy reaction – especially for the organization that employs him or her), or anything in the middle.

There is no point on the reaction scale at which berating or verbally abusing the developer is productive. Or even acceptable.

So take a deep breath and stick to the facts, Mack!

3 – What exactly seems to be the problem?

No, we don’t think that you’re making it up, that you’re dense, or that you’re bothering us with trivialities. We just want to know what kind of a bug you might be dealing with now:

• Did you get a weird error message?
• Did the application crash (i.e. suddenly shut down)?
• Did the application freeze?
• Does something look wrong?
• Is something missing?

4 – Do you have any evidence?

Yes, for god’s sake, we believe you. We don’t think that you’re off your rocker, if you have one. We need whatever evidence you have to help us identify the problem, find its source, and resolve it. So if you have it, give it up:

• Screenshot of the problem
• Exact wording of the error message
• Log file (if you don’t know what that is, don’t worry)
• Any other kind of output?

Also, if you’re a tester, please come prepared – you’re working with software, our software, and you know it might malfunction.In fact, if it didn’t, you wouldn’t have a job, now, would you? Since that is the case, please have some kind of diagnostic tools installed to help you gather the evidence: loggers, video captures of your testing session, etc.

5 – Do you have any special set up or configuration?

Especially if you are a developer or tester, you might have a special configuration file with specific setting that you are using. Please provide any non-sensitive configuration, or at least describe it. Anything you know about how you use the software can shorten the time it takes to fix the problem.

6 – What did you expect to happen?

No, it’s not a cynical way of stating that that’s the way the cookie crumbles. We don’t always know what you believe the normal behavior should be. You may be right, you may be wrong. If you’re right, we need to fix it. If you’re wrong (i.e. the infamous “not a bug”, a.k.a. “by design” / “as designed”), we need to fix our documentation. So please let us know what you expect.

7 – What did you do before the problems started?

Lemme guess: You think that it is your fault. Well, it isn’t. Period. It never is. Get over yourself. Stop wallowing in self pity and shame. This is me being cynical and stating that that’s the way the cookie crumbles. Nothing but the simplest programs can ever be completely defect-free.

What we mean to ask is “Can you please tell what steps I need to take in order to reproduce this myself”?

So please, list the steps you took, as best you can, so that we can repeat those, as many times as necessary, until we find the problematic part of the code that needs to be fixed. It is usually something in the code that is responsible for handling the steps you took, so this information is vital!

This is where a video recording, coupled with a log file and input recording would be nice. Testers – please use those.

8 – It works fine on my machine.

Okay, this one goes out to all you developers out there. There is nothing our coworkers hate hearing from us more than this line. It is not okay. It is still your responsibility to resolve the problem. I once worked with a manager that suggested that any developer that shrugs a defect off with “it works fine on my machine”, will be shipped off to the customer with his machine, in order to solve the problem. Said customer was in another country, where summer temperatures reached over 50 degrees Celsius (122°F!).  To my knowledge the threat was never actually carried out, but the developers there used the phrase less than any other team I’ve worked with.

What we mean (at least what I mean), and what we should say is “It works fine on my machine. This means that the problem is probably related to your environment. Can you please describe the conditions in which you are running this software?”.

So please describe your execution environment (re: what your machine is like), to the best of your knowledge. If you don’t know it, don’t sweat it – but if you are a non-technical user, and can find out this information (Wikipedia is a good enough explanation. You don’t need a PhD to understand most of it), you’ll really make your developer’s day:

• What version of our software do you have? Testers – you must know this. Devs – you must make this knowledge available!
• What are you running this on (smartphone, tablet, laptop, PC, server, virtual machine)?
• What operating system are you on – we might not know (Windows, Linux, Mac OSX, iOS, Android, Samsung? etc.)
• What version of the operating system do you have (Windows XP, 7, 8, 8.1, Mac OS 10.6, 10.7, 10.8, 10.9, iOS 6/7/8, Android 2.2/2.3/4.0/4.1/4.2)?
• What version of Office do you have (if any)? It may be relevant.
• If you know the software to be a sub-module or extension of some other software, please let us know what version of the host software do you have (e.g. you’re running an extension on Visual Studio – is it 2010/2012/2013? Which update?)
• If this is a web application, what browser are you using? What version?
• How much memory does your device have?
• How much free disk space does it have? All disks / volumes, please.
• Screen size?

9 – Are there any specific conditions / times that this happens?

Sometimes a bug will consistently appear whenever the application is executed. In other cases it might be limited to happening only sporadically:

• Does it happen every time you run it?
• Only every other time? Third time?
• Only mornings?
• Every Sunday at 2am? This is not a joke. If I know that the nightly backup happens at that exact time, I can deduce that the two events are interacting and this causes the problem.
• Does it happen only when some file is open in notepad?
• Does it appear to be completely random?

10 – Is this happening to anyone else, as far as you know?

This one goes especially for corporate and enterprise users, as well as testers in teams. Nobody expects Joe Six-Pack to go knocking on doors in order to figure out if he’s special or part of something bigger.

By now, you probably know that I’m not singling you out as an idiot, or something, but rather want to understand what is happening. If this is happening to everyone on your floor (but nowhere else), it might be some network issue. If it is only you, it might be a configuration issue, but if everyone on your team who’s using Internet Explorer 10, as opposed to 8, we know that there’s a compatibility issue in the code. The developers need to be able to identifying what is common to those who have the problem, that sets them apart from those who do not have it. It’s called differential diagnosis.

See, every bit helps. If you’re on a team, you really could go that extra mile to see if your teammates have similar issues. Especially if the software is built by the same company that you’re working for. You’re all in this together.

In Conclusion

We’re all in this together – developers, testers, operations – we usually (should) have the same interest – to make sure that we create a better product. So please – pretty please – with relish(!): be professional.

Thanks in advance,
Assaf – a developer.