We all hate finding bugs. Like ants and spiders they get into everything.  But also serve a purpose; ants fight termites and spiders eat other bugs. So can bugs in software be good? If you work in quality assurance or testing, they are good for business.

Here are Four tips to writing better bugs

Finding bugs should be hard, not writing about them

Finding bugs in your software should be the hard part. I have seen some really good and really horrible bugs throughout my career. The four tips that I am providing has helped improve the quality of bugs everywhere I have worked. These tips should help you make it easier to communicate the issue.

Tip 1: The Format

Throughout the years, I have seen some poorly written bugs and tickets. The worst of them involve assumed knowledge. If you are writing a bug report and expect either the reader or yourself to remember the details, you are wasting time. The more you spell out the steps the better! Let me share with you the format that I recommend.

Steps to Reproduce:
1. Open Chrome and go to…
2. Click on …
This needs to be spelled out in detail so that the product owner and developer know exactly how to reproduce the issue.

Expected Results:
Define what you are expecting to happen either by user acceptance criteria or reasonable user experience.

Actual Results:
What is the error? At this point you should include any screenshots and supporting information that you have from testing, such as if it only happens in FireFox but not Chrome.

Tip 2: The title

The title of the bug is important. While it’s not as important as blog title in catching your eye, it needs to explain the area and issue. Bug titles that are too long or too vague can slow down response time and obscure priority. Below I will break down the key parts of the bug title and show an example.

• Area: The general location where you found the bug. This usually includes the page name or section of the application.
• Issue: A quick explanation of the issue found with just enough detail.

Here are a few examples of bug titles.

• My Account – Update Card – Updating credit card is sending you to general error
• Search Results – Searching for books returns 404
• [PROD] Login Page – Cannot create new user account from Login page

Each example spelled out the issue in a clear fashion that anyone on the team could understand without going into much detail. The last example was a production issue and by using call outs such as “[PROD]” you are driving the team to issues in production that need to be addressed. Production issues are the only time that I would recommend using an environment call out. If you used one in each test environment, you would find that people quickly stop paying attention to them.

Tip 3: Screenshot

They say that a picture is worth a thousand words. Your screenshots should be worth at least as much if you do them right. A screenshot should help explain what is wrong and draw attention to the issue. That means you will need to mark up your screenshots before you attach them. Highlight the area in question with a red box so that you draw the readers attention to it.

There are two big problems that I have seen from screenshots. The first is the lack of call out in the image (as mention above). And the second is too many call outs in the screenshot. This second problem takes the form of either putting your steps to reproduce in the screenshot or trying to call everything out in one image. In the case of the latter I recommending using multiple screenshots so that information is conveyed clearly. Another issue I have seen is taking a screenshot of a stack trace. If your application has custom errors off and you get the actual stack trace, you should copy and paste the details into a text file and add it as an attachment.

Tip 4: Be concise

Bugs should be clean and clear. They are not intended to be novels but rather directions to problems. The biggest problem is in the directions. Using the format that I provided at the beginning will help, but you need to provide each step in the reproduction. Think of each bug you create as an instructional guide for a new team member in development. Start from the idea that they have never used the application before and you are walking them through how to use it.

Your directions need to be clear. Which browser were you testing in, did you clear cache before hand? If there are two ways to access the My Account page, which one did you take? Be detailed in the steps you followed to find the issue so that anyone can find and reproduce the issue.

Conclusion

The number one reason why bugs are rejected is because the developer could not reproduce the issue. Having a consistent way to document bugs in clear concise language will ensure they are fixed sooner.