My current project is releasing soon (yay!) and everyone is posting bugs. I wish there were fewer bugs reported of course 😂 but it is great to see so many things found before our customers get their hands the product.
To effectively fix these bugs it is important our developers get as much information as possible on how to reproduce the bugs. This way, the developer can focus on fixing it rather than trying to figure out what went wrong.
So in today’s post, I would like to share some tools and the format I use for reporting bugs. I hope it might help you make your developers just a tad less frustrated when being handed yet another bug.
Bug reporting format
It’s great to be as compact as possible, no one wants to read hundreds of lines of text. At the same time, there are a number of things we definitely need to specify. Here they are:
- Steps to reproduce
- Expected & Actual outcome
- Environment
- Evidence
Let’s break them down one by one.
Steps to reproduce
It’s vital for a bug reported to be possible to reproduce. If you are unsure, try and try again until you can find how to do it. If it seems to happen sporadically, make sure you have exhausted all the options you might think of before reporting it. It’s either your time or the developer’s time taken to track this down and chances are, you know better what you’re doing right now and the developer is probably on their 4th cup of coffee fixing the other hundred bugs raised the past week. So do help them out.
Keep it simple but try to put in anything that might lead to a different result. I usually add in input values or links as these are often the cause.
Expected & Actual outcome
This explains why you think it is a bug. Quite often, issues might not be bugs. For example, you try to add something in a field and you get an error back. This is bad UX but correct behaviour. Maybe the error message needs to clarify better what the expected input should be. If we know the expectation, it’s easier to determine the solution and priority.
For this reason, it’s incredibly helpful when receiving a bug to show what you expected and what you actually got instead. Best is to get actual images of the expected and actual outcome. Maybe you have a design specification and the actual app layout is different? Getting a picture of what is wrong immediately communicates the issue.
Environment
Next up is to explain where you found this bug. Anything that might explain why you got this issue right now and to determine if maybe it has been fixed already.
The environment information can include:
- if it is in local, staging or production environment
- URLs to systems you are using
- what device platform you are running
- Windows or Mac, if that’s relevant to your app
- Android or iOS, which version
- Emulator or physical device
- what build you are running, if there’s a version or so (even git commit can help)
- what browser you’re running on
- what user login or account you are using
- the time and place (geo/network)
Anything that’s relevant to reproducing it and might help the developer find log entries or so.
Evidence
Finally, anything that helps the developer troubleshoot. This can be test files, screenshots, videos, conversation, links to specs, log files. Anything really. Of course, don’t add in stuff that’s unnecessary or unrelated. If you’re saving an item and the bug relates one of the input fields, the image you’re using might not matter so don’t include it. Keep it to anything that might really help find and reproduce the bug.
Example bug report
So here’s how a bug report might look:
Tools
Screenshots are awesome
An old saying but true, a picture says more than a thousand words. It conveys meaning far more an much faster than whatever you can write. If you take anything from this post, I hope it is that you should always, if possible, show your bug with an image.
Highlight information that is important if you can and don’t crop. Things such as the URL address bar or time can actually help a dev conclude that you’re running on a certain URL, browser, time zone or something that might help troubleshoot.
I use these tools to quickly and effectively collect data:
Vysor and QuickTime to easily be able to grab screenshots from my phones on my Mac, I then use TechSmith Capture (previously Jing) or Kap to get the images/movies.
I use TechSmith Capture to easily grab screenshots (Cmd+Shift+1) and then annotate them with text or highlights.
Last but not least, Kap is an awesome tool for grabbing videos as GIFs. This helps to share exactly how things look where a single picture might not suffice. For example showing steps up until a crash or a failing animation.
These animations can get really big though so I recommend using a lower resolution and 10x FPS, that’s usually good enough to convey what’s happening.
Log messages are epic
Finally, a log message will usually tell the developer exactly what has gone wrong. By pressing Cmd+F12 you can open the Chrome developer console and in the Console tab you’ll find Javascript errors. This is usually a gold mine for anyone fixing a bug so do check if there’s something in there you can copy+paste in the bug report.
If you’re technical and you might be running an app in Xcode or Android Studio then getting the logs from there is also incredibly helpful. Finally, our team uses Stack Driver for logging in GCP. If you’re a developer raising an error, taking a dip into these logs and pulling out anything that might help troubleshoot a bug later is also incredibly helpful. Because a week later when you try to find what went wrong, you may not be able to find these logs anymore.
All in all
Fixing bugs can be fun but usually, we have more than enough of them and any little thing you as a reporter can do to help the overloaded devs is greatly appreciated.
Thank you for reading this and reporting your bugs neatly!