Best practice when reporting software bugs

  • Tuesday 2nd May, 2017
  • Words by Daniel Dyer

Using a bug tracking system is vital

A bug tracking system is a tool that everybody, not just the development team,  should use to report issues. Often we find clients and PMs feed issues to developers via email or spreadsheets.

Not reporting in a bug tracking system has the following negative consequences:

    • There are multiple places where the work list is stored so there is no one source for identifying the effort needed to release.
    • There is no status or workflow associated with the issue so the issue could easily be overlooked.
    • In order to identify the status the PM would need to be manually ask the developer  of the status.
    • Tester are often left out of the communication loop so they often don’t know the changes or issues reported and when an issues is fixed so don’t know when to retest it

Provide enough information to reproduce issues

Being able to reproduce an issue is vital to understanding how it can be fixed. If a developer can not reproduce the error when they will not be able to fix it. It’s therefore vital to provide enough information to aid the developer in understanding the issue well enough to fix it.

Vial information is:

  • Browser/Device/OS – if issue is specific to a particular Browser/Device/OS
  • Steps to reproduce – If the issue is caused by a specific sequence of steps then specify this by numbering each step you performed
  • Expected outcome – how you expect the system to respond or display information
  • Consequence of the bug to the user
  • Device you found the issue on
  • URL issue was found on

Meaningful bug titles

Bug titles should ideally contain the following:

  • Overview of problem
  • Page name or component/area of where the issue occurs
  • If the issue is specific to a OS/Browser/Device then specify it in the title
  • If the issue only occurs in a specific state for instance if the issue only occurs after selecting a button or tab then state this state information.

We recommend bug titles are wrote in the format : <Page name> – <browser if specific to a browser> – <brief summary of issue> e.g. “Homepage – IE8 – menu button is not aligned to the company logo ”


As the old expression goes “A picture is worth a thousand words” this is certainly true with screenshots. A screenshot can quickly give a people a good understanding of where the bug is located and what the issue is. Its can help people understanding the consequence & impact of bugs and help to assess the impact easier.

I recommend using a tool called Jing by TechSmith to create screenshots which also allows you to annotate and comment on the screenshot and target the areas relevant to the bug in question.

Expected outcome / propose fix

Specifying what you expect should happen or be displayed is important so that developers can perform the correct fix. If an expected result or proposed fix is not specified then developers may fix the issue in a different way which may be undesirable and could cause confusion for your user.

Be unambiguous

Ensure your issue is written such that it can not be misunderstood. Be as clear as you can so any member of your team can understand the issue with ease.

Specifying URL

Including a page url in the issue description quickly directs team members to the bug location and can speed up resolving an issue.

Specify consequence of the issue

Reporting the consequence of an issue is important for people to understand its impact  and helps to prioritise the issue effectively so issue which has greatest negative effect to the end user can be priorities highly so its fixed sooner.