There’s a lot of talk that learning to being able to (write) code is the new must-have skill. I think there may be something to that, but I think another key skill to be taught and learned will be how to write a decent bug report.
If you’re thinking, “I’m not an engineer or a QA person, I don’t need to think about bug reports,” you are dead wrong. Every time you say something isn’t working as you expect it to, from “this sandwich is missing the avocado” to “the sales numbers are wrong” you are in fact filing a bug report, and I’d wager bitcoins to blancmanges, it sucks.
Wake me when you learn to write a decent bug report
How often have you been on an email exchange with gems like these in it?
- “it doesn’t work”
- “these numbers are wrong”
- “it just doesn’t do it for me”
- “it’s still broken”
How is anybody supposed to fix these things with information like this? Do you call Car Talk and say, “my car is broken” and expect Tom and Ray to fix it without even telling them what color it is? We’ve all heard of constructive criticism and helpful feedback, but sometimes in the thumb-based world of constant partial attention, we forget that in identifying a problem, we are committed to help solve it, and that takes a little work. In that spirit, here are some ideas for writing better bug reports:
Describe what happened, or what didn’t happen. OK, most folks can handle this one, but the devil’s in the details – there’s a difference between “the toilet won’t flush” and “the toilet won’t flush because the handle fell off” and “the toilet won’t flush because I dropped my iPhone in there.” A little extra effort here can make all the difference.
Describe what should have happened, or at least why you know the actual result was wrong. Here’s where lots of people fall down. The people who have to fix stuff don’t necessarily know what you were expecting to happen, which in turn is not always the same as what should have happened according to the design. If you don’t know the right answer but still know you got the wrong answer, explain how you know that. Relatedly, if it used to work, describe how and when; if it works only sometimes, talk about the circumstances.
Bad: “I pressed the eject button and it didn’t work.”
Better: “I pressed the eject button and heard some clicks but the videotape did not come out. I pressed and held it for 20 seconds but still no tape. I did it yesterday and it worked immediately.”
Bad: “This report is wrong.”
Better: “This report shows 18 widgets last week, but Mike’s report shows 21 and I personally counted 20 on Thursday.”
If you’re making a second/third/nth attempt at getting something fixed, give some history of past attempts. You can’t expect that your issue is the only one they’re working on, and if it hasn’t been addressed, there’s a good chance they didn’t get or didn’t understand your prior communication.
Bad: “The coffee machine is still not working.”
Better: “Last Tuesday, I complained that the coffee machine was dispensing hot Mountain Dew. Today, it’s Code Red. Please restore it to delivering coffee as it did last month.”
In short, a little extra effort in identifying a problem not only makes it easier to solve, but it also shows your commitment to a collaborative solution, not just dumping a problem on somebody. This works for bigger-picture business stuff as well as broken technology, for example, “we’re not making enough money on this deal,” “these ad concepts stink,” “this product doesn’t compete in the marketplace,” all could use a bit more context, evidence and collaboration to solve.