LookFar Labs11 August 2016
How to Write Bug Reports: The Good, The Bad, and the Ugly
You’re testing your product and found a bug before your users did.
Success! Send it off to the developer, and it’ll be fixed. Mission accomplished, right?
Finding a bug is half the battle. Want to repeat yourself, send in tickets developers dread, and–ultimately–end up with everyone wasting time and being even more frustrated than when they started? Then, send ’em something like this:
Seeing an issue written like this only leads to more questions. “What, specifically, isn’t working about it?” “Where is it broken?” “How did you break it?” Answering these questions the first time around saves everyone time: time that you wish you weren’t spending explaining bugs, and time developers wish they weren’t spending asking about them.
Creating a bug reports should be like writing a recipe. It should tell you what you’re cooking, a list of ingredients you need, easy to follow steps, and what you can expect at the end.
The result is a template consisting of a Title, Environment details, Steps to Reproduce, Expected Behavior, and the Actual Behavior that’s happening. Let’s dive into some specifics, give some examples, and talk about how to write a bug report the right way, the wrong way, and the ugly way.
A title should be an easily digestible, one-line synopsis of the issue. A bug report is something your project team will use to reference the issue, so keep it concise and informative.
The Good: Searching for an Email by Sender displays an error and closes the application
The Bad: Searching for an Email and the application crashes
The Ugly: Search for an email is broken
As technology continues to march forward, so do our options for interacting with software and the web. For QA, developers–and yes, even users–this means we need to be specific about what we’re using when recreating issues. Using a specific file or in-app configuration? Include that too.
The Good: iPhone 6 / iOS 9 / Firefox 47.0.1
The Bad: iPhone
The Ugly: [Blank]
Steps to Reproduce
Providing a step-by-step process of what you did to find the issue gives direction to your users. Each step should be a specific and separate action. If you’re doing it correctly, your reader should be able to easily navigate through your software. A good practice here is to go through the steps you wrote, line by line, making sure every detail is written out. This gives you the chance to fine tune and add anything you may have forgot the first time around, leaving no room for confusion.
- Log in on an iPhone via Firefox
- Navigate to My Inbox
- Click, Search Current Mailbox and type in “email@example.com”
- Click Search
The Bad: Log in and search for a sender
The Ugly: Search for emails
What were you expecting to happen after your last step? If you’re working off requirements, acceptance criteria, or a user story, reference it.
The Good: All emails from, “firstname.lastname@example.org” should populate the search results, per Acceptance Criteria 3.2a
The Bad: Emails from the sender show up
The Ugly: Emails appear
What actually happened? Did you receive any error messages?
The Good: A “500 Internal Server error” popup message appears and the application closes
The Bad: An error pops up and crashes the application
The Ugly: It crashes
Now, let’s put all those components together…
…and we wind up with a well-defined, easy-to-reproduce bug report. Send your development team something like this, and you’ll be filling in a bunch of extremely important blanks for them and saving a bunch of valuable time in the process.
Fixing a bug starts with reproducing it. If you can’t reproduce it, how will you know if it was fixed? Developers can try to make changes and updates to what *could* be the problem, but unless you can make a before-and-after comparison, you can’t truly be certain it’s resolved.
Providing all the pertinent information upfront leads to bug tickets that everyone loves. Detailing issues does take more time and effort, but it saves time and frustration in the end. Good bug reports = happy developers, and happy developers = better products.