Secret ingredients to quality software

Do you know the right way to report bugs and give feedback/suggestions?

Last updated by Tiago Araújo [SSW] on 25 Nov 2021 02:29 am (5 days ago) See History

When reporting bugs and giving product feedback, it is essential that you are as descriptive as possible.

This will save the both you and the developer time and frustration in the long run.

Make sure you always explain and give as many details as you can of how you got an error or a bad experience. Detailed and useful descriptions can make finding the solution quicker and easier.

For bugs, the goal is to include enough details so the developer can easily reproduce the error to find out what the problem is.

For suggested features it is best to:

  1. Draft your suggestion
  2. Call the Product Owner sharing screens, then add “checked by XXX”
  3. When using a backlog, create an Issue/PBI and @mention relevant people (they should get an email)

    If there is no backlog and an automatic nicely formatted email, you may send all the text and details via a normal email

Try to have one issue/PBI/email per bug/suggestion, but if the bugs/suggestions are related or very small, then you may group them together in a single email.

Figure: Bad Example - This email isn't going to help the developer much - it is vague, has no screen capture or other details to help reproducing the error

Figure: Good Example - This email includes the product name and version, the category of the issue (BUG), a screen capture, and informs the user's system

When possible, a great template to follow is the Functional Bug template from the ASP.NET open-source project. Spending time to provide as much detail as possible, by ensuring you have the 3 critical components:

  • Steps to reproduce,
  • Expected outcome, and
  • Actual outcome

Figure: Bad example - Lack of details

Figure: Good example - We can easily identify more the one way to improve the UX and there's a clear suggestion to action

Videos can make things extra clear

Better than a good description is a screen recording. This should be followed for a more detailed report. Use Snagit or Camtasia to record your screen.

Figure: Good example - Recording bug reports in a video can make the issue clearer to see

Figure: Good example - Giving feature requests via video

Should you send this to the Product Owner or the Tech Lead?

It depends on the team, but often the Product Owner is busy. If you know the Tech Lead and your suggestion is obviously a good one, then you should email the Tech Leader and Cc the Product Owner. The Product Owner can always reply if they don’t like the suggestion.

For a bug email:

To: Tech Lead
Cc: Product Owner
Subject: Bug - xxx (or use PBI @mention)

For a new feature email:

To: Tech Lead
Cc: Product Owner
Subject: Suggestion - xxx (or use PBI @mention)

Note: You may have a group email such as, You would only Cc this email when a greater visibility is required.

Use emojis and prefixes for PBI/Issues titles, or email subjects

When you create a bug/suggestion to a backlog, it's a good idea to add emoji in the title. Not only does it look nicer, but people can look at the item and take in the necessary information quickly.

This means that anyone looking at the backlog can glean its nature at a glance, rather than having to read each item to know what category it is (5 bugs, 2 features, etc). Examples:

  • 🐛 Bug - Calendar is not showing on iOS devices
  • ✨ Feature - Add 'Back to menu' item to top navigation

Check out the rule on which emojis to use in Scrum.

Tip: GitHub Issue Templates can help you with that.

Adam CoganAdam Cogan
Cameron ShawCameron Shaw

We open source. Powered by GitHub