I have a document sitting on my desktop titled, “howtofixabug.rtf.” It’s a catchy title. At first glance, it’s a technical document, and it could easily have become one. Instructions on how to use our internal bug tracking software, to file an issue with software. That is, strictly speaking, exactly what the document is meant to do. The goal of the document was to walk some of our user acceptance testers through the process of filing their first bug.
There’s one line at the beginning of the document that I keep picking away at. My most current rewriting of it is: “It’s all about communication. An effectively reported bug is more likely to be fixed.”
Why is that line so problematic? Why is it so important that I’ve rewritten it a dozen times? Normally if an introductory line like that were so problematic, I’d delete the thing and be done with it.
It turns out that bug filing is not just about pumping accurate information into boxes or working pull down menus properly, it’s about communication. You have to explain the problem in such a way that whatever busy project member who reads it will understand the problem, understand why they should care, and have some hope of approaching it for a resolution.
With that in mind, I condensed my definition of “bug” into approximately three sentences; although I suspect that you could write entire books on that alone, I’m not sure that it would be a best seller, and I know that our user acceptance team would not read it.
For our purposes, a “bug” is a problem that you have with software. It may be that the software is acting in an unexpected way (broken functionality or surprising behaviour) or that it is not meeting your needs as a user. (Poor usability, failing to serve the intended purpose, failing to meet expectations, etc) You can file anything as a bug, but bugs are fixed according to priority; resource constraints often mean that critical issues are fixed first.
In the end, I documented eight steps to filing a bug in our bug tracking software, some of them with piles of sub-components. Many of the steps were just technical tricks, but the last two seem to be the most critical: Summary, and Description.
To me, one of the most interesting problems was writing the bug summary. Describe your problem in one sentence, without being unclear or overly subjective. Pound as much data as possible into a minimum number of words, remain compelling, keep in mind keywords for searches, cross referencing and reports, and make sure it all forms a catchy title for future reference. No problem right? This is where the twitter generation is supposed to excel right?
Everything critical is in the title and bug summary, because bug filing is about communication. It’s hard to break down into rules or power point bullets, but I’ve got a few:
1) Be clear and concise. Short sentences are better than long ones; focus on getting the message across as quickly as possible. Don’t make your reader work for it.
2) Avoid subjective data. It’s okay to compare expectations to reality, but avoid talking about your emotions. “It takes the page 15 minutes to load,” is good, but “it’s really boring waiting for the page to load,” is bad. We’re sharing information here. Where possible, I like to dedicate the first two lines to a quick, “expected result,” and “actual result.”
3) Avoid “I.” This might help with #2. By referring to “the tester,” or “the user,” you inform the reader that your bug is reproducible, and that the experience you’re describing is universal.
4) Use understandable, exhaustive reproduction steps. Numbering steps helps break this down, like a walkthrough or instruction manual. Anyone should be able to follow the steps without any issue, needing other data, or needing to make decisions.
What else am I missing? It’s all about transmitting information, and demonstrating why the issue is, in fact, an issue. In a sense, it’s about advocacy. If you can’t easily demonstrate that something is a problem, it’s not likely to be fixed. Objectively describing the problem as quickly as possible is key to convincing readers that there is a problem, and that it’s a fixable one. Any kind of missing data, incorrect information, or dismissible personal experiences could make a bug look less important, or make it less likely to be fixed.