TIPS FOR RESPONDING TO BUG REPORTS

If you look at the bug reports on many big open source software projects it’s almost like the developers have a bug report Magic 8-Ball. Reports come in and developers just give the Magic 8-Ball a shake and spit out the response. You’ll see the same four or five terse answers over and over again, “working as designed”, “won’t fix”, “need more info”, “can’t reproduce” and so on.

You'll see the same four or five terse answers over and over again, "working as designed", "won't fix", "need more info", "can't reproduce" and so on.

At the same time large software projects often have very detailed guidelines on how to report bugs. Developers know that the average user doesn’t think like a developer so developers create guidelines, checklists and other tips designed to make their lives easier.

The one thing you almost never see is a set of guidelines for responding to bug reports. The other side of the equation gets almost no attention at all. I’ve never seen an open source project that had an explicit guide for developers on how to respond to bugs.

If such a guide existed projects might not be littered with terse messages that not only discourage outsiders from collaborating, but showcase how out of touch the developers can be from the users or testers of their software.

The reporters are trying to help. They may be frustrated, they may even be rude, but remember they're upset and frustrated with a bug, not you.

It’s time to throw away the Magic 8-Ball of bug reports and get even better at improving your software with these simple tips for responding to bug reports.

1. Don’t take bug reports personally. The reporters are trying to help. They may be frustrated, they may even be rude, but remember they’re upset and frustrated with a bug, not you. Now they may not phrase it that way, they may think they’re upset with you. Part of your job as a developer is to negotiate that social gap between angry users and yourself. The first step is to stop taking bug reports personally. You are not your software.

2. Provide explanations in your responses. Avoiding Magic 8-Ball responses like “can’t reproduce” and “need more info” isn’t just about being polite, it’s about improving communication. The bug reporter may not be providing helpful info, but in dropping in these one-liners you’re not being helpful either. In the case of “need more info” take a few seconds to describe the information that will help you fix the bug. Need to know the OS or browser version? Then ask for that. If you “can’t reproduce” tell the user in detail what you did, what platform or browser you were using and any other specifics that might help them see what’s different in their case.

3. Be collaborative, and avoid “Us vs. Them”. This is related to point one, but remember that the reporter is trying to help and the best way to let them help you is to, well, let them help you. Let them collaborate and be part of the process. If your project is open source remember that some of your best contributors will start off as prolific bug reporters. The more you make them part of the process the more helpful they’ll become over time.

4. Avoid technical jargon. For example, with really non-technical users, you might say “the address from the web browser address bar” instead of “URL”. This can be tricky sometimes since what you think of as everyday speech may read like technical jargon to your users. When in doubt err on the side of simple, direct language. Of course, if you’re working in open source and patches, some technical jargon is likely alright. Along the same lines, don’t assume too much technical knowledge on the part of bug reporters. Don’t just say, “what’s the output of tail -f /var/log/syslog?”, tell them where their terminal application is, how to open it and then to cut and paste the command and results you want. A little bit of hand holding goes a long way.

5. Be patient. Don’t dismiss reports just because they will involve more effort and research. It’s often said that there is no such thing as writing, just re-writing. The same is true of software development, fixing bugs is software development. The time and research it takes to adequately respond to bug reports isn’t taking you away from “real” development, it is the real development. Remember to set aside and invest the time in digging as deep as you can before dismissing a given report.

6. Help them help you. Think of this as the one rule to rule the previous five. Bug reports are like free software development training. Just because you’re the developer doesn’t mean your users don’t have things to teach you, provided you’re open to learning. Take everything as a teaching/learning opportunity and you’ll find that not only do your bug reports make your software better, they make you a better software developer.

Don’t dismiss reports just because they will involve more effort and research. It’s often said that there is no such thing as writing, just re-writing. The same is true of software development, fixing bugs is software development.

It can be hard to remember all this when you have a pile of bugs you want to quickly work through. Try to resist that urge to work through all the new bug reports before lunch or otherwise rush it. Often times it’s more effective to invest a few extra moments collaborating with the reporter to make sure that bugs are handled well.