How to write (and read) a bug report
All you need to know is that there is a problem, my work here is done
What is a bug?
A bug is when somebody who is paying money for your software, or not paying money for your software1, uses your software and then:
(what they expect to happen) != (what actually happens)
There are a lot of different scenarios based on the following general role archetypes:
The Customer: actual users of the software, the people paying them, the people paying for the software, the people married to these people, people who might use the software in the future, people who keep promising you they will use the software, that the check is in the mail, et al.
The Product Manager: the product owner, product manager, project manager, subject matter expert, support staff, or any other non-software-building entity that talks to customers or makes decisions on what you don’t work on.
The Developer: technical staff in charge of building and keeping the software running, typically Product Development, or Application Development, which includes Quality Assurance.
Different combinations of agreement between these three roles create confusion. A bug report is meant to solve this confusion.
Sometimes, the Customer and Product Manager agree on the bug, but the developer doesn’t:
misunderstanding or missed requirement, the developer did not know that the large boat we just built is expected to have planes land on it. The customer (General McStuffins) seems upset that this requirement was missed, and that this misunderstanding led to a poor beta test landing.
Sometimes, only the Customer believes there is a problem:
It is a major missed requirement, in which the customer expects something because all other competing software has it, but yours does not. The large boat should have large guns, all the other navy aircraft carriers have large guns, its so obvious that they are needed.
It is a misuse of the software, a training issue, in which the customer puts a piece of bologna into the CD-ROM drive and then files a bug report.
It is a mistake by the customer in which they tells you that something happened that didn’t. Or the developers says “that can’t happen”. This is referred to as denial of reality or gaslighting.
Sometimes, only the Developer believes there is a problem:
It is technical debt, which is when the developer thinks it is a problem, but the customer and product manager don’t agree because they don’t know what you are even talking about.
The Product Manager very rarely has a situation in which neither the Developer nor the Customer agrees with them. If this happens, the manager is no longer a manager but a visionary (or very wrong).
If Customer, Product Manager, and Developer all agree:
There is a fault with the software, meaning that the developer agrees that it shouldn’t be doing that.
Each fault leads to multiple failures. Like when you let your cat drive your car: each mailbox that they hit is a failure, born from the fault in letting them drive.
Sometimes, all parties disagree on what is happening. A customer receives an error that the product manager and developer have never seen and cannot resolve in the system. This is called failed to reproduce2.
How Reality and Truth Work
Here is a table3 representing these realities:
As you can see, the people paying you tend to define your reality, unless you actively prove them wrong. Customer-facing folks usually avoid telling customers they are wrong, or soften it “well, bologna is round, so I can see where you are coming from - did it heat it up at all after you put it in the drive?”.
Customers => Product => Development
Decisions flow from left to right, and reality is defined left to right. Sometimes, truth and science flow from right to left, but you must manage it carefully.
What a bug report actually is
I say all of this to explain what a bug report is. A bug report is meant to bring all parties into agreement. It is a written record of a shared reality.
Its primary function is to give enough information to a developer so that they agree on the problem's existence, urgency, and exact details. A good bug report prevents anyone from denying or dismissing the problem and makes it easier to fix it.
Primary sections of a bug report
Version Affected: software doesn’t have versions anymore, ya heard? Well, there are only two versions: Not Shipped and In Production. Make sure you don’t put anything stupid like “Current” in the bug report - remember this bug report might outlive your children.
Evidence: Screenshots, spreadsheets, a transcript of whispered conversations at a bar during a user conference, recordings of emotional customers proving the issue exists, etc.
Comments: This is where people put their fan fiction, including proof that they are human and can do simple pattern recognition:
Emotional Commentary: This is where customer-facing people need to declare hedges and prove that they are working hard on the issue and understand its urgency:
this is IMPORTANT, need to fix PERMANENTLY and then determine root cause ASAP6
We need a software system free of issues, we talked about this last fall - MUST-FIX
There must be a big difference in this issue and what we just tested, because I tested all scenarios that I think will provide cover for my career, and they are all attached with checkmarks next to them this is not on me please don’t let this be on me
Reproduction steps: this is when exact steps to trigger the problem are detailed. This is the most helpful part of the bug report for a developer, and having it greatly increases the chance of a fix happening this year. Think of this as steps to create new evidence. This is rarely filled out, unless the bug report is created by a QA staff member. Most of the time it is filled out with hundreds of words of nonsense that boil down to: “I launch system (screenshot of me launching), and then the problem is so obvious I can’t explain it omg please fix ltr bai”
Reading a bug report
The person who gets assigned the bug is expected to figure out what all the previous programmers overlooked or didn’t see, understand what foreign code is doing, and then fix it, for all time, immediately, dammit. The person who writes the bug report must click some buttons and then hit save.
The quality of the software your organization produces is a function of a few key behaviors, and one of them is high-quality, detailed bug reporting. The average bug report is filed by someone with a cursory examination of an issue who thinks it wise to get it into the hands of a developer as fast as possible, like a hot potato.
Ideally, bug reports detail the issue (what looks wrong, what it should look like) and include steps to reproduce it. This only happens sometimes, like when a stopped clock is right twice a day.
As everyone who has ever maintained an open source project can agree with - if people use your software, they think it has an implied warranty.
Also, the title of your sex tape.
The Venn diagram of the situations I’m trying to describe is vile, and I will not publish it.
Not it isn’t, it just has a similar shape. Is it always the same issue when a boat sinks? It goes to the bottom of the water each time. “Is this the sinking issue? I thought we fixed that after the Titanic”
No, absolutely not, you idiot. Oh, wait, actually, let me check.
Good advice honestly, because I was going to determine root cause super-slowly, and then and only then maybe fix it, but temporarily.