Writing Clear and Effective Bug Reports

Clear Bug Reports

You’re looking at an existing product and you think you’ve found a bug. Your bug report needs to include (1) what the feature is, (2) how you’re expecting the feature to work, and (3) what the feature is actually doing at the moment.

1. What the feature is: For the front end of the website, the admin, or an API point, a URL can be sufficient. If it’s a certain part of a page, name the title of the section and include a screenshot. If it’s a visual thing rather than a data thing, try it on more than one browser or mobile device, or at least specify the environment where you saw the error.

2. How you’re expecting the feature to work: This turns out to be where miscommunication most often occurs. It’s also the easiest section to leave out of a ticket. It will feel like you’re writing exposition that everyone already knows. Unfortunately, you can’t read the minds of designers, developers, or users, nor can they read yours. Developers probably can’t remember what you said if you mentioned what you had in mind at a scrum. Write it down so everyone can refer back to it and angrily point at it later.

3. What the feature is actually doing at the moment: Screenshots are great. If a hard error is returned, include the stack trace or a link to the stack trace. If it’s working in one place and not in another, take a screenshot of the two URLs side-by-side. If your screenshot includes  features you’re not addressing, take a smaller view or draw an arrow to the point you’re talking about. For transitions and scrolling issues, take a video or call a second team member over to make sure the way you’re describing the experience makes sense.  If it takes more than visiting the URL or mobile app screen to see what you’re talking about, include how you’re able to reproduce it and how often if it doesn’t happen every time.

These guidelines apply to any user, internal or external, trying to communicate with the development team. If you’re a QA person, all of the above is contained in the description and attachments of the ticket. Filling out the rest of the fields make the difference between a ticket getting the appropriate attention instead of languishing in the backlog.

Effective Bug Reports

Before you decide to create a new ticket in JIRA, see what other tickets already exist. Find other tickets about the same feature. Find the ticket where the same thing happened but in a different environment. Find the ticket that was closed because no one could reproduce it. Find the ticket that’s already open that a developer wrote and you didn’t understand until you saw the bug yourself. If possible, reopen or add to those existing tickets. If that’s going to create more confusion, keep this tickets open in separate tabs so you can link your new ticket to them to prevent developers from closing your ticket as a duplicate.

In JIRA at my job, we use a limited number of Projects (Web, Mobile Apps, and a few particular internal departments) and Issue Types (Epics to group tickets within projects, Bugs for most other things). Choosing the Issue Type as New Feature or Task can give a project manager a better idea of how long a ticket will take, but since Bug is the default we end up using that most often. We completely ignore the Due Date and Component fields and we only use Affects Version and Fix Version for the mobile apps, where there are clearly delineated versions.

Adding a JIRA ticket

The Summary is best when it addresses (1), (2), and (3) as described above. Given the implicit character limit of the width of an Agile board (70-80 characters), it makes more sense to address (1) and either (2), (3), or the specific environment where you were able to reproduce the bug. If possible, include a salient keyword so it’s easy to refer to the bug at meetings and search for it in JIRA.

Set the Priority as the lowest possible option unless a project manager or a pillar of the business suggests otherwise. The QA team can help everyone understand the pros and cons of prioritizing bugs, but we’re not the ones to do it. Bug the project managers, not the developers, if your bug isn’t getting the attention it deserves.

If there’s a project currently in development and it’s clear a particular developer’s work caused the bug, make that developer the Assignee. If it’s not clear which developer may have caused the bug, make the lead developer the Assignee and add suspect developers as Watchers. If it’s not clear how the feature was intended to work or how the bug should be fixed, assign the ticket to the lead UX designer. If it’s not clear if the project is being worked on, assign the ticket to the project manager. Add yourself as a Watcher to all tickets so JIRA will email you when someone goes rogue from the workflow. See also: My Biggest JIRA Pet Peeve.

While Environment seems like it should be used for the browser version, OS version, or model of phone, that information gets lost unless it’s included in both the Summary and the Description. I use Environment for an important but too often forgotten part of the software development lifecycle: listing the people who were affected by the bug so you know who to email when you fix it. It’s in a location on the ticket that’s both easy for project managers to find and easy for developers to ignore.

See the Clear Bug Reports section at the top for what you need to include in the Description and Attachments. If there’s more than one attachment, change the filename to what differentiates them from each other (before and after, browser version, date, production vs. test server) before you upload them.

Add the ticket to the current Sprint if the priority has been set higher than the default and the project manager requests it. If there’s an upcoming themed sprint that the bug falls into, put it there. Otherwise leave it in the backlog for the project and product managers to prioritize. Include the ticket in an Epic if the Project designation is too broad or the ticket will get lost in the backlog without it.

JIRA automatically assigns a unique ticket number to each new ticket using the Project slug and the next available integer that corresponds to the permalink domain/browse/[Project slug]-[integer]. When tickets are moved between projects, old URLs redirect to new ones.

Respond to my jibber jabber

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s