mikebernat.com Web-Development, Design, Usability

Bugs are an inevitable part of any development project that most people loath or at least generally dislike. If you take the time to examine this phase of a project you will find that it's not the bugs that really irk you, but the way they are presented, described, and handled.

Ok, so maybe bugs are not the worst part about my job but they can be very effective at frustrating the hell out of me. After you get over the fact that you are not the world's greatest programmer and are indeed as fallible as the rest of us, you can begin to look at bug reports as an opportunity to better yourself. Learning from your mistakes is a huge part of the job and can be extremely beneficial. However, no matter how vetted any particular programmer may be, most will cringe when they see a bug drop into their inbox.

Why is that? This particular developer may have seen every type of bug report known to man. So why do they still fear something that they haven't even had the chance to look at? The simple fact is that once you have been around the block a couple times, you know that there is a good chance there will be several messages sent back and forth between developer and client before there is even a solid idea of what the problem really is. Even then it could be days before the programmer can reproduce the problem.

Does any of this sound familiar?

Client: It doesn't work.
Developer: What doesn't work? Can you be more specific?
Client: The website doesn't work.
Developer: It looks fine to me. What do you see when you try to pull up http://www.example.com?
Client: That page looks fine.
Developer: So what is it exactly that is not working for you. Can you give me the url and describe in detail what is not working, and what you expect to see?
Client: http://www.example.com/ins/ign/ific/ant/page.php shows a slash before the apostrophe in the second sentence (...it\'s all about...).

This conversation could easily have taken a full day's worth of emails. And, meanwhile the developer is freaking out because someone said the entire site was not functioning for him and he can't figure out why. At this point you begin to wonder who else can't access the site and how pissed your boss is going to be, and what you could have done to cause this, etc etc etc. As the conversation progresses you learn that it is actually a very trivial problem on a page very deep in the site that no one will probably visit anyway. Granted, it is a bug and needs to be addressed but is very much the opposite of how big the problem sounded in the beginning.

Most clients/users don't realize that reproduction is the key to fixing any bug. It sounds simple but in some situations it's like searching for the holy grail. The problem is that developers can't read user's minds and sometimes it feels awkward to respond to some of the things that they come up with. You don't want to sound condescending (even if you really do) when asking for more information but you would like to get the point across that they did not leave enough details to adequately diagnose and treat the problem. Hopefully, at the same time, you try to teach them to not leave such vague reports in the future.

Required Information

There are several things that clients need to detail when leaving a bug report.

1. A general summary of what the problem is.
2. Their interpretation of the severity of the problem.
   • This could be totally different than what you might expect.
   • It's nice to know that something is totally unimportant to you as the coder but could mean the difference between life and death for the client.
   • This way you know to either get on it right away or at least leave them a message with some sort of timetable to ease their pain.
   • Conversely, what could seem trivial to the client could be causing unknown problems all over the place and would need to be addressed much sooner.
     
3. Exactly where the problem occurred.
   • On what page, screen, dialog, menu. An exact URL, for example, would be great.
   • Where precisly on the aformentioned page is the problem.
   • Screenshots can be godsends.
     
4. Precisely what they did leading up to the problem.
   • I can not emphasize this point enough. The smallest things to the user could be the key to solving the problem.
5. What browser/os/version/etc are you using?
   
6. Any other information they feel is important.
   • This is an open-ended question because there could be so many other things revealed here.
   • Has this problem happened before?
   • Does it seem to occur at certain times of the day?
   • Is it a leap-year?
   • Did your horoscope tell you to expect terrible things today?
     

Most, decent, bug-tracking systems have fields for all these things but they are rarely filled out. A user who might have a million other things to do that day may think that leaving something like 'This page doesn't work' is all the coder needs to do their job, but rarely is that the case.

Whenever I am met with an obscure bug-report, I remind myself that this is just a simple user, and they did not really mean to make my day more frustrating by giving me no details, a strict time-table, and a piece of their mind. My strategy to deal with these types of reports is to very calmly state that I am having trouble reproducing this bug. If would be good enough to help me out by describing exactly what they are seeing, what they expect to see, where they are seeing it, and the steps they took to get to this point it would help me immensely.

If doing this yields no results then I usually either try to meet up with them so they can reproduce it in front of my eyes or perform some type of screen-sharing session with them.

/rant

I know I have been using examples for web-developers but these ideas could just as easily be associated with any other type of programming.

Some helpful/entertaining links:

http://www.codinghorror.com/blog/archives/000459.html - Why programmers file the worst bugs

http://www.chiark.greenend.org.uk/~sgtatham/bugs.html - How to report bugs effectively

http://www.youtube.com/watch?v=BcQ7RkyBoBc - This about sums it up (HILARIOUS)

If you have any tricks as to how to deal with clients/users who never leave enough information without making them feel inconvenienced, and/or an idiot, please share your secrets!