When we write bug reports, most of the time we have a clear vision of what just happened or what steps were taken in order to reach to a situation where something not expected happened. It is obvious to us at the moment, so we communicate it with very few notes because it’s very obvious, paste a screenshot and that should make it obvious to the developer what went wrong, right?
The problem is, most of the time, that bug report is the first exposure to a developer. When a developer reads a bug report, theories and possible causes of the problem start to arise, the developer starts to think about how the data flowed through the system to reach that situation, after all, software is just a black box that takes some input and transforms it into some output
So we may know the output with a bug report that has a screenshot or has a shallow description of what happened, however we do not have the input that kicked off some process that caused a bad output ! An output can be generated by many, many processes, there are many ways to generate a single output, a simplified analogy is for example someone reporting a problem with a calculator saying: “I got the result 1 when I should have gotten result 3 !” What a developer does first is, “What operation using what inputs should give the number 3 but is given number 1?” There are infinite ways to get the number 3 with different combinations of numbers and operations, and we need to find out which of these is causing the problem, a LOT of time is spent figuring out what operation caused the problem.
If in that bug report of above, the reporter said instead: “I punched the buttons: 4 - 1 and got 1 but I should have gotten 3!” we would have received the input information to understand what process kicked off the process that caused the bad output, cutting completely the initial research time to find out what caused the problem and immediately jump into a solution, the initial research time can account for over 70% of the time spent fixing a bug.
What is a good bug report?
First, take some time to go through the bug report process for the Chromium project (Click the top left "New Issue" button) just go through the steps and see how much information they ask.
First and foremost, we need to know what steps were taken to lead to that situation? Or also named: Steps to reproduce.
This is covers the sequence of actions taken to lead to the bad result. Some of the questions that are answered there is:,
- what page were you visiting
- what did you click
- what was your user
- what module in the system were you manipulating at the time.
Document every step as thoroughly as possible, even if it is very obvious at the time, After 2 days if a developer asks for feedback you will have forgotten what exactly happened adding more time to a resolution of a bug, as the chinese proverb says: The palest of ink is better than the best memory.
Then we need to know What did I expect to see? Or otherwise named: Expected results
Here, the bug reporter must describe in detail what was expected to happen, should the message been sent? Should my changes have been saved? Should I have access to see some resource?
Software moves at a very fast pace, and it is possible that misconceptions happen, by stating what is the expected behavior, we can sometimes clarify how some feature should work. Also, by stating what should have happened, it makes it easier for the developer to find out what logic flow path was taken and where to look first.
Finally, we need to know What you actually saw? Or otherwise named: Current results
Here you will describe exactly what you are seeing, how it looks, what moved around which shouldn’t have or what stayed which should’ve moved.
Most of the time, we skip everything to this step by posting a screenshot, however this is bad because, as stated above, we can’t do much by just knowing what you saw. Alternatively, once we know the scenario and what happened, reaching the point of What you actually saw? is trivial, because we now know how you reached to that state.
Here’s where you finally add screenshots or a video. Sometimes a screenshot is not the most helpful thing in the world. A video is, most of the time, useful because we can see the steps being taken, that’s one of the biggest reasons why a video is a good reporting tool, but if we already have those written, then a video is just a nice to have.
Another very valuable tool to have is a screenshot of your chrome developer tools. You can find instructions on how to open it here
This is how you would use it:
- Open the chrome dev tools and switch to the Console tab
- Try to replicate the bug you are reporting
- When you reach the bad results, take a screenshot of the output in the Console tab and add it to your bug report.
The above doesn’t always apply, as a rule of thumb, if you see output with a red background, it means that there is something wrong with some of the UI logic, if you don’t it means it’s possibly a backend problem in which case the problem won’t be displayed in the dev tools.
And finally notify the corresponding people about the problem.
As per the Chromium report form, you need to specify what area is the problem affecting. Maybe a formal concept of "area" doesn't exist for some teams, but most of the time we have an idea of what part of the system is the domain of most developers. Why is this important? It is important because teams have a lot of communication going on in all different channels: issue tracker, IM, email notifications, user reports and we need to make that flow of information as effective as possible. A developer might be receiving notifications of issues/tasks outside of its current domain and it can drown notifications where that person attention is needed, this make triaging issues less efficient by having notifications overflows. Also, by notifying/assigning to the correct person, that person can triage the problem and assign it to the developer that lasted worked on the component giving problems if need be.
Conclusion
A good bug report can cut a big bunch of time spent in fixing a bug. Although it is an extra effort from the reporter to fill a more complete bug report, the value provided by it is very well worth it. Not only it saves time for developers to find and fix the issue, but it also serves as a documentation tool for everyone to better understand the product, by getting everyone more involved with the processes, knowledge about the whole system grows, a clear report cuts time going back and forth between reporter and developer that may be better spent somewhere.
