One of the single most important things for a software company is getting useful bug reports. If you’ve ever gotten a message consisting of “it doesn’t work” or “it’s broken”, you know how completely useless it is. In fact, it’s not just useless, it’s worse. Now you have to ask all of the standard follow up questions… so you’re set even farther behind.
So in case you’ve never submitted a bug report or are new to software development or happen to be one those people, here are some things to get you moving in the right direction.
There are three things I need for a useful bug report:
First, I need to know what happened. Okay, so it didn’t work, but something must have happened. Did you get an error message? Did something blink? Did it make a noise? Did you smell smoke? Did it act that you didn’t do anything at all? Some systems – from dotProject to the Nintendo Wii – will occasionally give you useful error reports and point a developer in the right direction.
Second, I need to know what you did. If you clicked these buttons in this order, write it down. If you put “monkey” into a field expecting a dollar amount, write it down. If you’re using a particular version of software, write it down. Here’s the nasty thing about every developer in the world. If we can’t figure out how to make it happen again, we can’t fix it. Even worse, if we accidentally repeat it once, make a change, and can’t do it again, we’ll think that we’ve fixed it only to find out later that we were wrong. If you can give detailed steps on how to reproduce the issue and it happens consistently, it’s easy for us – and you – to confirm that it’s fixed. Some organizations will even add it to their testing plan.
Next, I need to know what you expeced to happen. Did you expect the display to blink and say “armed”? Was your selection supposed to turn red and display a “confirm delete” dialog? Just like the first point, this behavior – or lack thereof – can give a developer an idea of what is really going on. More importantly, it helps eliminate misunderstandings on functionality. Quite often a bug is submitted when a user just expects X and instead Y happens. Y might work just fine and need clarifying language to logically distinguish it from X. Annoying yes, but it happens regularly and becomes an opportunity to improve understanding of the system.
Finally – and most importantly – I need to know how to contact you. Even if you provide all of the above information, having a direct way to contact you can provide valuable insight. Every developer/company/group approaches this aspect a bit differently, but I personally go a step further. I work on the principle that if they have taken the time and effort to give useful, actionable information, they should be encouraged however possible. Therefore, I release the patch to them as soon as it’s ready and I – with authorization – publicly identify and thank them and their organizations in the announcement and release notes.
On that front, I want to thank the numerous people who have submitted bugs, requests, and questions about the Project Importer for dotProject. The current release – v1.5 – has had contributions, suggestions, and fixes from a number of people. But some of them have been gracious enough to pass along their actual Microsoft Project files to give me the precise information to reproduce the problem. I can honestly say that there has been nothing else so valuable and I believe is one of the principles which the Open Source Community is based upon.
So thank you.