I work in the space between front-end web people (who write content and talk to web users) and back-end web people (who write code and build web applications). I help wonks[1] communicate with geeks[2]. A fundamental element of success in this pursuit is the Useful Bug Report. (There’s a bit of a rant coming up, so if you want to skip straight to the how-to, here’s your link.)
The tracking system we use for bugs/feature requests/etc. works well. It isn’t perfect.[3] It leaves room for gaps in wonk/geek communication. For example, the instructions for the “Description” field say:
Put as many details as possible in the Description, including links to the pages involved, usernames/emails, and your browser version.
These instructions aren’t very helpful to a wonk who is trying to write a report that will be useful to a geek. Minute detail does not necessarily produce good bug reports. On the other hand, neither does an “I was on our website and something is broken—I clicked something, and it looked weird” approach.
I just finished writing up a more practical “How To” sheet for the wonk side of my team. I would have thought this kind of information would already be widely available, but a quick Google search for “how to write a good bug report” led me to:
- Specific bug reporting systems which require you to log in before giving you any information (boo), and
- Some “how to write clear bug reports” tips from bloggers who don’t write clearly (by my standards) and/or are condescending.
Not terribly helpful. I shall now rush in to fill this information gap.
~~~
How To Write a Useful Bug Report
The way you describe a bug to developers can make a big difference to how quickly they can resolve an issue. The better the bug report, the less initial troubleshooting/diagnosis the developers need to go through.
Your “Description” field [in our internal system] should contain a little narrative that includes the answers to the following:
1. Where were you? (Website / product or application / URL / section of page)
2. Were you logged in, and if so, with what permission levels? (e.g., not logged in, logged in as user or admin)
3. What operating system and browser were you running? Include version numbers if you can (e.g., Windows XP 2002 SP 3 + Firefox 10.2.0). It can be illuminating to check a bug in multiple operating systems and browsers, and then add something like this to your description: “First encountered this on my work desktop setup, where I’m running Firefox 10.2.0 over Windows XP 2002 Service Pack 3. Tested in Chrome 17.0.963.56 m and Internet Explorer 8.0.6001.18702; same results. I also tested it from home where I’m running a (really old) Mac, OS 10.5, and Firefox 9ish; same results, only slower.”
4. Describe the bug:
a. What did you click, or what action did you take right before the bug made itself known (e.g., added something new to cart, clicked “Submit”)?
b. What did you expect to happen when you took that action?
c. What actually happened?
d. What does “fixed” look like? That is, do you want the fix to reflect the “what did you expect” state above, or something else—like hiding the broken thing, or reverting to an earlier build?
This should give [our in-house development team] enough to go on to make a good start at diagnosing the issue, and save a bunch of back-and-forth emails or ticket comments.
~~~
Remember, dear reader: The above is a basic cheat sheet I wrote for my own team. Your mileage may vary. Other things like bandwidth/connection type, other programs you were running (like adblockers or portals like Blackboard), whether you were streaming Pandora at the time, etc. can also be helpful diagnostics. This isn’t the One True Way. It’s my way, today.
[1] Wonk: I use this term to mean “Expert; having a deep and detailed understanding of a particular content area which is little known by the general public.” Etymological sources differ; some suggest it is drawn from “know” spelled backwards, as in “to know your material backwards and forwards.” Go back to reference point
[2] Geek: I use this term to mean “A person who is proficient in digital technologies; who knows how to write at least one type of computer code and/or is comfortable installing, troubleshooting, or repairing computer and networking hardware.” As a person who identifies as a wonk and a geek (as well as a nerd and occasionally a dork), I use these terms with love and respect. Go back to reference point
[3] None of the bug/feature tracking systems I have used are perfect. They all have quirks, or leave something out that you wish they put in, or have more features than you’ll ever use. Go back to reference point