tl;dr: skip to the bottom to see the template.

Perhaps the most generic title I’ve ever written. It sounds like it’s straight out of a 1,000+ page 80’s textbook on “Testing Duties in Middle Management”.

The problem is that I frequently run into terrible bug reports. Googling brought about some decent results, but the articles I found were still lacking. They often took either the side of the software engineer or the side of the tester, and rarely the side of the user. Even rarer were explanations or reasons given to “why” the steps were what they were. Many missed vital steps altogether.

I plan on walking you through a user journey interfacing with tech to illustrate the “why” and the need for these missing steps. We make a couple of assumptions:

• You are working with more than 1 person on your team
• Engineers have power or influence in deciding which bugs to fix
• The engineer has a greater responsibility than solely following your orders (otherwise you can demand whatever you want)
• Taking the perspective of a co-worker, not a random user

Define “bug”

“I found a bug — I can’t edit this ledger item from last month.”

This came from a colleague who had found a charge that looked to be incorrect. The problem with her request is that this “inability” was by design.

The root of the issue was that we were using different definitions of a “bug”. In order to work well together and avoid conflict, it is important to decide on what a bug is.

I’ve seen all of the following as definitions of bugs:

• Something that does something other than expected
• Something that causes bad user experience
• Something that can be fixed in under an hour

Wikipedia’s definition is “all-encompassing” and for our case unuseful:

“A software bug is an error, flaw, failure or fault in a computer program or system that causes it to produce an incorrect or unexpected result, or to behave in unintended ways.”

My preferred definition is:

• “An action or state that is causing unintended results”

The largest flaw in this definition is that it requires knowledge of what are the intended results.

In the example above, ledger items were intentionally unchangeable in the past because editing them would delete the history. Since this history was available to the user it could look like we were changing past financial records (bad news). We had alternative options for dealing with this scenario and the response was not any sort of coding fix but was instead training on those alternative options.

We had to decide on a definition. In this case, we ended up using my preferred definition (listed above).

Writing a bug report

Co-worker (Co): “The website is broken”
Software Engineer (E): “What part?”
Co: “The main site”
E: “The main site is working for me”
Co: “The contact page”
E: “I see it just fine — what’s broken?”
…

I’ve seen hundreds if not thousands of these conversations: they drive engineers nuts. This is because there are broken expectations on both sides.

As a user, you’re frustrated. Something you’re using is stopping you from doing your job — and it is some engineer’s fault. You’ve got deadlines/clients waiting/rushed to get to the next thing, can’t someone just fix it?

All of these thoughts are 100% valid. It is the engineer’s responsibility to make things work, to test them, and to provide a workable system. It is a reality, however, that all systems have bugs. This doesn’t mean that you, as a co-worker, should have to spend type documenting bugs, but if you don’t it’s near impossible for engineers to fix them.

A well-written bug report will also reduce the back-and-forth, hopefully to zero. Any time back-and-forth is necessary, it can easily exponentially increase the time from when the report is received to when it’s fixed. If everything is there in the first place, it can take a couple hours as opposed to days or weeks.

Side note: If you think there are far more bugs than normal, I’d reach out to whatever manager you can about implementing better QA (Quality Assurance) practices.

Therefore, it is in both your best interests to write a clear and concise report with the following information:

• Title
• Steps to reproduce
• Expected result
• Actual result
• Attachments
• Impact

Let’s go through them one by one.

NOTE: It is useful to only include 1 issue in 1 bug report. This helps with tracking and will get the bugs finished faster. If an engineer sees multiple bugs that will take a combined 4 hours to do, he may not be able to fit that in between everything else. Doing it “part of the way” generally leads to mass confusion. When the bugs are separate, multiple engineers can more easily pick them up or can fit them in between other actions.

Title

A brief/succinct description of what’s happening.

Ideally, this should also give an indication of the part of the system that is affected. It should also state what is happening as opposed to what you cannot do.

Incorrect:
“Can’t read text on website”

Correct:
“Contact page text overlaps after clicking submit”

At a glance, an engineer could easily identify and perhaps estimate the length of this bug fix.

Steps to reproduce

If you are able to reproduce a bug at will or know how to do it, this is the single greatest piece of information that will aid an engineer in fixing a bug. If you cannot reproduce it, provide as much information as you can surrounding how it happened.

Engineers have to be able to reproduce a bug in order to actually call it fixed. If you know how to do that, it can save tremendous amounts of time.

Providing the shortest possible steps with as much detailed information as you can is important.

Incorrect:

1. Went to Contact Page
2. Submitted the form
3. Text overlapped

Correct

1. Clicked “Contact” link from Home Page on the top navigation bar
2. I typed “Jane” in name field, “[email protected]” in the email field, and “hello” in the message field
3. I clicked the “Submit” button
4. Text overlapped

It is very difficult to determine what information is useful (we have no idea if the information in the fields is relevant at all), therefore providing the exact information as detailed as you can brings about the fastest resolution to a bug.

Expected result

Both parties, engineers and users, are often confused when reports miss this information. The user thinks it’s obvious and the engineer doesn’t understand what you’re complaining about.

“I clicked create but I’m still on the same page.”

The user feels like it’s obvious that something should have changed and they should be somewhere else. The engineer knows that some pages, after clicking “create” changes pages, and some don’t. Defining your expectation helps to determine very quickly what your upset is, and therefore be addressed more quickly (and reduce back-and-forth).

Also, make sure that you’re not writing circular logic.

Incorrect:
“I expected the contact page to not be broken.” (circular logic)

Correct:
“I expected the contact page, on submit, to take me to another ‘Thank You’ page without any overlapping text.”

Actual result

You may have already stated this in the title, in which case this is repetition. Often, however, you will need more data here. If possible, provide a comprehensive description of the result.

Incorrect:
“Text overlayed.”

Correct:
“I clicked submit, a loading icon appeared, then what looked like a box of text appeared over the form that said thank you for submitting.”

Attachments

Very simply, take a screenshot of the error if you can. If you want to be extra thorough, take a screenshot of the before & after state. Or perhaps you’re using an attachment (such as importing data from an Excel file), include that too so the engineer can reproduce it using the same file.

I consider this step to be provisionally optional. Include it if there is anything visual to be seen. But if the bug wasn’t visual, such as not receiving an email, it is not necessary.

Impact

This is one of the most neglected steps and one that I haven’t found in any other “how-to” on bug reports. Some people put priority: “Low”, “Medium”, “High”, “Urgent”, but this has fundamental logic issues.

In order to be able to place the priority of the bug, you would need to know about all the other bugs and other things the engineer might be working on.

“Impact” is a statement of your understanding of the effect of the bug. This allows the engineer, who presumably has more information in regards to other bugs and issues going on, to prioritize appropriately.

I do think that there should be an “urgent” checkbox. This checkbox should simply send a ping or special flag in the message that indicates that the user believes it to be urgent. This can help an engineer get quickly alerted if something major is broken — but he is still setting the actual priority, which should be understood from the user side.

If possible, state terms of impact with numbers.

Incorrect:
“Doesn’t allow me to send contact requests.”

Correct:
“My department usually sends 20 contact requests per day which is now stopped because we’re not sure if they are going through.”

And that’s the last of the fields!

Responsibilities

“Didn’t you miss environment details, who reported the bug, how to contact them, etc.?”

Perhaps, but I don’t think that’s the user’s responsibility.

As software engineers, we are asking a lot of our users to report so much information because of our mistakes. The least we can do is gather all the information we can from them without them explicitly stating it.

If you have a bug report form, and it’s not just an email, you should be able to gather all the environment information from the specific version of your browser to the actual signed-in user and any relating information to you. In fact, some bug reports are good enough that they will automatically capture a screenshot.

If you do not have this ability, then yes, you will need to add additional fields for the environment, contact information, and anything else that you can’t gather automatically.

There is a special case for “Page URL” if you’re working on a website. I hope/prefer people to include this in “Steps to reproduce”, but that’s not abundantly clear. Likewise, they may submit the bug from a page other than the one that had the error (and so it becomes impossible to gather this from other data). It may be useful and it may not.

All together now — Bug Report Template

We now have a complete bug report:

Title
Contact page text overlaps after clicking submit

Steps to reproduce

1. Clicked “Contact” link from Home Page on the top navigation bar
2. I typed in “Jane” in name field, “[email protected]” in the email field, and “hello” in the message field
3. I clicked the “Submit” button
4. Text overlapped

Expected result
I expected the contact page, on submit, to take me to another ‘Thank You’ page without any overlapping text.

**Actual result
**I clicked submit, a loading icon appeared, then what looked like a box of text appeared over the form that said thank you for submitting.

**Attachments
(**attach your screenshot)

**Impact
**My department usually sends 20 contact requests per day which is now stopped because we’re not sure if they are going through.

As an engineer, I would love this report and probably be able to fix it within 30 minutes without any back-and-forth.

Comment below if you have any questions or disagreements, I’d love to discuss!