5 tips on writing a good bug report

Every development team strives for a perfect software solution, free of bugs and errors. But even the most carefully designed solutions are bound to have logic errors, unit-level bugs, and other types of software issues.

The key to a great solution is a reporting workflow that allows you to efficiently address these issues when they are identified. At the heart of such a workflow is the bug report — documentation that provides details about the issue you’ve uncovered. Several technical experts share their recommendations on creating a bug report below.

Use these 5 tips to create an informative bug report

1. Describe the bug clearly

Vlad Anhelov, a quality assurance engineer at HelpCrunch, says it’s important that bug reports include clear descriptions of the bug. Generic descriptions like “the button doesn’t work” aren’t informative and make it difficult for the development team to prioritize their resolution efforts.

Start with a clear summary. “This is the first thing a developer reads, and it should answer the what, where, and when,” says Anna Serguts, QA engineer at Orangesoft.

Anhelov agrees, saying reports should provide a brief, yet descriptive summary of the issue that answers the key questions Serguts called out. For example, instead of “the button doesn’t work,” write, “the [name] button on the [name] page crashes the program after [action(s) that led up to the crash].”

Keep in mind that you may have to translate information about bugs that were originally identified by end users. Anhelov notes that people outside the development and QA teams tend to focus on how the issue made them feel rather than the issue itself. “That’s why it’s vital,” he says, “for your team to use a standardized bug report template so everyone knows what information is needed to resolve the issue.”

2. Give a detailed account of the environment

Alex Saltykov, QA lead at KeenEthics, says it’s important to understand not just the bug’s behavior, but also the context in which it occurred. Include information about the browser or mobile app used, the version of the software, the operating system of the device, and so on. This will help the development team determine the contexts in which the bug occurs, as the issue may only impact, for example, dated devices or operating systems.

3. Outline precise steps to reproduce the bug

To effectively fix a bug, developers must be able to reproduce it, which requires precise steps since the bug may only occur under specific conditions or after a unique series of actions. Saltykov says steps are precise if a developer can reproduce the bug at least three times. “If you fail to reproduce it all three times, then try to reproduce it a total of 10 times and record how many times the bug appeared — for instance, six out of 10 times.”

Serguts adds that unclear steps can prevent developers from reproducing a bug at all. “If the tester or user does not accurately convey how the bug occurs, the development team will most likely reject the bug until it’s identified again.”

4. Include attachments for clarity

“Pictures are worth a thousand words, and GIFs and videos even more,” says Jay Gadi, engineering manager at Soapbox. Always try to get a screenshot, GIF, or video of the bug as it happens. “It’s 100 times easier to solve a problem, especially from a technical point of view, when you can see the issue firsthand.”

Saltykov echoes Gadi’s sentiments, noting that the significance of attachments is often underestimated. He says a properly visualized bug in a screenshot will save a lot of time. “If you can’t catch bugs with a screenshot, record a video with comments about the actions you took, the expected outcome, and the actual result. Don’t forget to attach crash logs if there are any.”

5. Make one person accountable for creating bug reports

Gadi recommends appointing one person to create bug reports. “This is usually your product manager or engineering manager,” he says. “If there is no one appointed, people often assume that someone else will handle the paperwork, and the bug may get lost.”

If your workflow doesn’t support a single person handling all bug reports, be sure to encourage accountability with your team — whoever discovers a bug (or is informed about it from a user) needs to create the report.

If you apply the above tips consistently across bug reports, you’ll be able to build an effective workflow that keeps your development team on track and your users happy.

Want the full rundown on the topic? Check out the complete guide we created on bug tracking.