Why do we report issues?
To work out the best way to communicate ‘Bug’ (or more accurately, issue) reporting, we first need to look at the purpose behind them. On the surface, it is easy to just say that bug reports are pointing out things that are wrong. In reality, they solve multiple problems:
Identifying something that is not working at all
Identifying something that doesn’t match the specification or design
Identifying something that is confusing
Suggestions or ideas to make the software better
Determining which of these pertains to our issue report goes a long way in properly getting the best resolution.
So, how do we log a better issue report?
Issue reporting is an important part of software development and critical to refining a solid software product. Despite being so necessary, developers (and designers) sometimes bristle at receiving them. Why? Most of the time, it is all in the delivery.
The key to logging a good report is to put yourself in the shoes of the person reading it. There are a couple important questions that will be on the developers’ minds when they first read it, so let’s review those.
It is very important to identify what type of report is being sent. These can be defined differently, but in general, we use the following:
Bugs - something is broken that was working before
Feature - additional functionality added to the current site
Improvement - a suggestion to change the way something works
Developers want to fix things and make great code, so calling a suggestion a bug is basically an accusation that they failed. So, try to stick to observable facts. State your understanding of what was expected and what was unexpected. It can feel a little robotic, but it will help tap into that natural desire to fix things rather than putting your developer on the defensive, and you will be amazed at the results.
When I click this fields nothing happens.
[Bug] In the admin user section, when editing Mary Johnson’s profile, I was expecting to be able to select her role from a pre-populated list of options. However, when I click in the professional role field, no options appear.
When an issue is being reported, it is tempting to only think of what is in front of you. You may want to send a picture of the problem, but oftentimes a photo is not enough on its own to convey where you are in the program. Include some context about where you are in the process or application so the developer can easily slide in to the right spot. It is critical to lay out what happens and what is expected, as well as give an example of how to recreate the same outcome. Oftentimes, issues exist because we are using software differently. Step-by-step instructions to reproduce the outcome will generally make the problem obvious and also lead to a solution much faster.
The arrows aren’t working.
I went to the homepage and attempted to click the arrows and scroll through the photos. My steps were as follows:
• Navigated to the"Services" page
• Clicked on the logo to return home
• Scrolled down and attempted to click the arrows
• Upon clicking the arrows, I noticed the image didn't change.
All too often a developer revisits a bug a few weeks later and the person who originally posted the bug can’t remember how to reproduce it. If you don’t understand your own bug report a month later, it doesn’t have enough detail. If you write the report for future “you,” all parties will be better able to understand the problem as time passes.
Tone Matters too