Doctor, I need some Xortoplex
Posted on: June 4, 2009
I just finished working on a problem. I might say it feels pretty good to find a real problem that was hiding somewhere and nail it down. The fix was quite simple, not more than 5 minutes work. However, it took me about 6 hours to find what is the problem, or should i say four weeks, 6 hours, and 5 minutes?
It all started, like many other cases, with a customer support email. Some question about something. Emails went back and forth, suggestions were raised, information was requested, and so it went on and on. The problem, you see, is that if the problem this customer had was so obvious, we would see it as well. But we typically don’t! because typically, it is not so obvious.
The problem is that in order to fix we need first to understand, and in order to understand we need to see. And if we can not see it, at least we can see all kind of other information that will gives us clues. So it took us 4 weeks to see it, 6 hours to understand what is going on and when it happens, and once all was in place, 5 minutes to fix it.
So why did it take 4 weeks to see it? Why couldn’t we see it on the first problem report?
This is what we call bug reporting. When you go to the doctor, you try to tell him what is wrong and why did you come to him. You will not say “I feel horrible and I need Xortoplex and I need it now since I have a very important meeting and if you had half a brain you would know what it is and fix me up now”. Well, you’ll be surprised how many bug reports sound this way. Now, don’t get me wrong. I don’t mind the half a brain thing, nor the conclusion that Xortoplex is needed. What I mind is that the problem report has no useful information I can use to start answering the problem. Something like “I have a headache and fever. I vomited twice since breakfast and my teeth are falling.”. Now, if after that you would like to add that last time Xortoplex worked wonders that is fine, but that can not come instead of a report of the problem.
So, how can we report a problem in a way we can reposed effectively and solve it? This is a great article that will better explain what are we looking for in a report and why.
To sum it up, here are a few rules of thumb for effective reporting.
* Keep in mind that we are on the same side! We want to help. We want to solve the problem. Since we do not sit in your office and did not see the problem, we need your help. The more information we get, the faster we can understand what the issue is, the faster we can respond.
* The best outcome of the report is to have the programmer see the failure with their own eyes. Since they can’t be with you when that happens, give them detailed instructions so that they can make it fail for themselves. If you can attach screen shots, please do. If you have files used or generated, such as images, PDF files, log files, please send them.
* In case the programmer can’t see it failing themselves, he needs to understand what went wrong. Describe everything in detail. State what you saw, and also state what you expected to see. Write down error messages, if they were. Like above, files used in the process, like image files, PDF files and log files ate worth their weight in gold.
* By all means try to diagnose the fault yourself, but even if you do, you should still report the symptoms.
* Be ready to provide extra information if the programmer needs it. If they didn’t need it, they wouldn’t be asking for it. They aren’t being deliberately awkward. Any information on your system will help, OS, version, memory, hard drive, images used….. Better, just send this information in the first place. Be aware that small details you don’t see as important might be very important.
* Write clearly. Say what you mean, and make sure it can’t be misinterpreted. “It crashed” might be interpreted in many ways, and so does “it didn’t work”. One liners are great for punch lines, but are pretty useless for problem diagnostics. Don’t worry. You can not over explain.
Anyway, if you missed it above, it is well written and easy reading.
Digilabs Technologies Blog 
Leave a comment