Rules to Better Bug Management and Product Feedback

Do you know the best way to manage product feedback?
Effectively managing product feedback is key to improving your product. While platforms like UserVoice and UserEcho have been popular, GitHub emerges as a superior choice for modern software development.
UserVoice and UserEcho
- UserVoice - Known for its voting and ticket system, it allows users to enter suggestions and administrators to track feedback
- UserEcho - Similar to UserVoice, providing a platform for user feedback and suggestions
Why GitHub is Better
- Integrated Development Workflow: GitHub integrates directly with your development workflow, making it easier to turn feedback into actionable items
- Transparency and Collaboration: GitHub's open platform fosters transparency and collaboration, allowing users to see the progress of their feedback
- Richer Interactions: Beyond simple voting, GitHub allows for richer interactions between developers and users through comments, labels, and reactions
Using GitHub for Feedback Management
- GitHub Discussions - For general feedback or discussions around feature or support requests. Facilitates community engagement and broader discussions.
- GitHub Issues - Ideal for reporting bugs or tracking work. Use labels to manage and prioritise feedback effectively.
- Project Boards - Use GitHub Project Boards to track the progress of feedback implementation, providing visibility to your team and users.
✅ Figure: Using GitHub Discussions to gather feedback for Next.js
Link: github.com/vercel/next.js/discussions/categories/ideas
GitHub’s comprehensive tools provide a more integrated and transparent approach to managing product feedback, making it the recommended choice for software teams. UserVoice was as popular platform to collect, manage, and prioritize user feedback. It has a voting and tickets system out of the box.
More Information - Google Trends
Figure: Google Trends shows that "UserVoice" is declining in popularity (see trend line), while "GitHub Discussions" is slowly growing

Do you know how to report bugs and give suggestions?


<introEmbed
  body={<>
When reporting bugs or providing product feedback, it’s important to include as much relevant detail as possible. Make sure it reaches the right people through the right channel - ideally the product backlog, or email if needed. A well-written report saves time and avoids frustration for both you and the developers.
  </>}
/>
## ✅ Use YakShaver

The best way to report bugs or share feedback is by using [YakShaver](https://yakshaver.ai/).

YakShaver is a smart tool that simplifies how you report issues and give feedback. Instead of spending time writing a detailed report or figuring out who to send it to, you just record a quick video and YakShaver handles the rest.

Using AI, YakShaver analyzes what you've said and automatically routes the issue to the right person. This means you don’t have to worry about choosing the right backlog, tagging the right team member, or following up to make sure it landed in the right place. It speeds up communication, reduces misunderstandings, and allows everyone to focus on solving the real issue instead of getting bogged down by process.

<youtubeEmbed url="https://www.youtube.com/shorts/0TPo98R1tnI" description="Video: What is YakShaver? | Ulysses Maclaren (1 min)" />

---

## ❌ Do it manually

If you can’t use YakShaver for some reason, follow these 8 tips to do it right manually:

* [Tip #1: Draft your bug with enough details](#tip-1-draft-your-bug-with-enough-details)
* [Tip #2: Draft your suggestion with the complaint and what you expect to see](#tip-2-draft-your-suggestion-with-the-complaint-and-what-you-expect-to-see)
* [Tip #3: Should you send this to the Product Owner or the Tech Lead?](#tip-3-should-you-send-this-to-the-product-owner-or-the-tech-lead)
* [Tip #4: Should you email or put it in the backlog?](#tip-4-should-you-email-or-put-it-in-the-backlog)
* [Tip #5: Do you make it easy to find all the backlog in your company?](#tip-5-do-you-make-it-easy-to-find-all-the-backlog-in-your-company)
* [Tip #6: Make sure when using backlog, the Product Owner will still get an email](#tip-6-make-sure-when-using-backlog-the-product-owner-will-still-get-an-email)
* [Tip #7: Separate PBIs](#tip-7-separate-pbis)
* [Tip #8: Use emojis and prefixes for PBI/Issues titles, or email subjects](#tip-8-use-emojis-and-prefixes-for-pbiissues-titles-or-email-subjects)


<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Making the Product Backlog the main source of tasks',
    shouldDisplay: true
  }}
  src="/uploads/rules/report-bugs-and-suggestions/report-bugs-and-suggestions.png"
/>

### Tip #1: Draft your bug with enough details

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.

The goal is to include enough details so the developer can focus on the development work more rather than trying to figure out what the feature requirements or bugs are.

Things to include:

* Steps to reproduce the error
* OS and browser details
* Screenshots\
  **💡 Tip:** Copy and paste the text for searchability
* Video for more complex bugs (more info below)

Learn more:

* [Do you have a clear definition of a bug?](/definition-of-a-bug)
* [How to produce a good bug report?](https://www.boxuk.com/insight/what-makes-a-good-bug-report)

<emailEmbed
  from=""
  to="&#123;&#123; SUPPORT EMAIL &#125;&#125;"
  cc=""
  bcc=""
  subject="Your software"
  body={<>
    ## Hi

I'm having a problem with your software. When I run it, it says something about registration and then exists.

Can you tell how to fix this?

Thanks
  </>}
  figureEmbed={{
    preset: "badExample",
    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",
    shouldDisplay: true
  }}
/>

<emailEmbed
  from=""
  to="&#123;&#123; SUPPORT EMAIL &#125;&#125;"
  cc=""
  bcc=""
  subject="🐛 BUG - PerformancePro - Error on startup"
  body={<>
    ## Hi team

I'm having a problem with your PerformancePro software. When I run it, this is what happens:

1. Run the application from Start | Programs
2. Access opens
3. I get this error:

   ![](/uploads/rules/report-bugs-and-suggestions/error-software-bur-report.jpg)

    Here is the transcription for searchability:

    > An embedded page at chrome-extension://laookkfknpbbblfpciffpaejjkokdgca says:
    > Could not find resource: longtail performance counter.
    > Prevent this page from creating additional dialogs.

I have the latest version of all my software. I am running Windows 10 and Office365.

Can you please investigate and let me know how to proceed?

Thanks
  </>}
  figureEmbed={{
    preset: "goodExample",
    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",
    shouldDisplay: true
  }}
/>

#### Functional Bug template

When possible, a great template to follow is the [Functional Bug template](https://github.com/aspnet/Home/wiki/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
* Actual outcome

<emailEmbed
  from=""
  to="Danny"
  cc=""
  bcc=""
  subject="SSW TV"
  body={<>
    ## Hi Danny

Where is SSW TV on the navigation?

Adam
  </>}
  figureEmbed={{
    preset: "badExample",
    figure: "Bad example - Lack of details",
    shouldDisplay: true
  }}
/>

<emailEmbed
  from=""
  to="Danny"
  cc=""
  bcc=""
  subject="SSW Website - Can't find SSW TV link"
  body={<>
    ## Hi Danny

I've searched the SSW website and can't find a link to SSW TV.

1. Navigated to ssw.com.au
2. Scrolling though home page. Nothing.
3. Checked the menu at the top. Nothing.
4. About Us? Nope.
5. Services? Nope.
6. Products and Support? Nope.
7. Training? Nope.
8. User Group? Nope.
9. Me, thinking... "OK. Now where? Most likely, the SSW company description will list it..." Navigates to About Us... scrolling down... Nothing.
10. Me, thinking... "OK. Weird. Let's go back." Me, goes back to homepage.
11. Me, thinking... "Is there a site map?" Scrolls to bottom of page. Clicks sitemap link. Nope.
12. Me, thinking... "Ctrl+F for TV? Nope."

### Expected result

When I navigate to ssw.com.au, I should see at the top of the page clear link to click on "CHECK OUT SSW TV!"

### Actual result

Couldn't find a link on the page.

1. Can you help users to get to SSW TV website from SSW website

Adam
  </>}
  figureEmbed={{
    preset: "goodExample",
    figure: "Good example - We can easily identify more the one way to improve the UX and there's a clear suggestion to action",
    shouldDisplay: true
  }}
/>

#### Make it extra clear with videos

Better than a good textual description of a bug report is a screen recording. This should be followed for a more detailed report. Use [Snagit](http://www.techsmith.com/snagit.html) or [Camtasia](/production-do-you-know-how-to-start-recording-with-camtasia) to record your screen.

<youtubeEmbed url="https://www.youtube.com/embed/y9vsGY1hYN0" description="" />

<figureEmbed figureEmbed={{
  preset: "goodExample",
  figure: 'Video: Good example - Recording bug reports in a video can make the issue clearer to see (1 min)',
  shouldDisplay: true
} } />


Recording a stepped user flow of actions that walk through through an issue is another excellent way of reporting a problem that is easily understood and reproducible. There are many tools you can use to make recording these steps easy, for example [Steps Recorder](https://support.microsoft.com/en-us/windows/record-steps-to-reproduce-a-problem-46582a9b-620f-2e36-00c9-04e25d784e47) which is built in to Windows, or [Microsoft's Test & Feedback extension](https://learn.microsoft.com/en-us/azure/devops/test/perform-exploratory-tests?view=azure-devops#install-the-extension&WT.mc_id=AZ-MVP-33518) for Chrome, Edge and Firefox.

See our rules for setting up and using these tools at [Do you use Problem Steps Recorder?](/do-you-use-problem-steps-recorder/) and [Do you do exploratory testing?](/do-you-do-exploratory-testing/)

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "goodExample",
    figure: 'Good example - Using a tool to record steps replicating an issue is a great and simple way to report a problem that\'s easy for a developer to understand and reproduce',
    shouldDisplay: true
  }}
  src="/uploads/rules/report-bugs-and-suggestions/psr3.png"
/>

### Tip #2: Draft your suggestion with the complaint and what you expect to see

Define all the requirements as per [Do your User Stories include Acceptance Criteria?](/acceptance-criteria)

Better than a good textual description of a suggestion request is a screen recording. This should be followed for a more detailed report. Use [Snagit](http://www.techsmith.com/snagit.html) or [Camtasia](/production-do-you-know-how-to-start-recording-with-camtasia) to record your screen.

<youtubeEmbed url="https://www.youtube.com/embed/VDZSfHJ7GNU" description="" />

<figureEmbed figureEmbed={{
  preset: "goodExample",
  figure: 'Video: Good example - Giving suggestion requests via video (5 min)',
  shouldDisplay: true
} } />


### Tip #3: 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.

If you are unclear use IM to ask, but remember [the golden rule to not send tasks on Teams](/important-chats-should-be-in-an-email).

<asideEmbed
  variant="greybox"
  body={<>
    **For a bug email:**\
&emsp;&emsp;**To:** Tech Lead\
&emsp;&emsp;**Cc:** Product Owner\
&emsp;&emsp;**Subject:** Bug - &#123;&#123; SUMMARY OF BUG &#125;&#125;

**For a new feature email:**\
&emsp;&emsp;**To:** Tech Lead\
&emsp;&emsp;**Cc:** Product Owner\
&emsp;&emsp;**Subject:** Suggestion - &#123;&#123; SUMMARY OF SUGGESTION &#125;&#125;
  </>}
  figureEmbed={{
    preset: "default",
    figure: 'XXX',
    shouldDisplay: false
  }}
/>

### Tip #4: Should you email or put it in the backlog?

Always go for backlog if you have access to a backlog management system, otherwise email relevant people.

<asideEmbed
  variant="info"
  body={<>
    You would only Cc group emails - such as `all@northwind.com.au` - when a **greater visibility** is required.
  </>}
  figureEmbed={{
    preset: "default",
    figure: 'XXX',
    shouldDisplay: false
  }}
/>

### Tip #5: Make it easy to find backlogs within your company

It is recommended to keep track of active project backlogs on the company intranet, while also including the Product Owner and Tech Lead contact information, coupled with a link to the Teams channel of that project.


<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'An intranet page with links to projects’ backlog to make it easy for everyone to find. Note some projects have more than 1 backlog.',
    shouldDisplay: true
  }}
  src="/uploads/rules/report-bugs-and-suggestions/do-you-know-how-to-report-bugs-and-give-suggestions.png"
/>

### Tip #6: Make sure when using backlog, the Product Owner will still get an email

Create an Issue/PBI and @mention relevant people (GitHub and Azure DevOps will generate a nicely formatted email)

See rules on [Do you know when you use @ mentions in a PBI?](/when-you-use-mentions-in-a-pbi)

### Tip #7: Separate PBIs

If they are all related to one area, then you could consider putting them together. Otherwise don’t bunch them up.

See rules on [Do you send tasks one email at a time?](/do-you-send-tasks-one-email-at-a-time)

### Tip #8: 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](/which-emojis-to-use-in-scrum).

<asideEmbed
  variant="info"
  body={<>
    **Note:** [GitHub Issue Templates](/github-issue-templates) can help you with this.
  </>}
  figureEmbed={{
    preset: "default",
    figure: 'XXX',
    shouldDisplay: false
  }}
/>

Do you have a clear definition of a bug?
The answer to this question can make or break contracts. We think that it's such a fundamental issue it has to be captured clearly. This is how we strictly define a bug.
A software issue can be classed as a bug where:
1. The application crashes to code (excluding bugs resulting from third party products, e.g. "blue screen of death" or crashing in a third party data grid that we cannot control); or
2. The application displays data inconsistent with the specified business rules; or
3. The application is missing functionality specified in the specification; or
4. The page design/layout is substantially inconsistent with the agreed mock-ups.
As you can see, bugs come in different shapes and sizes. Some bugs are minor, like alignment on a webpage. Some bugs are major, like blocking bugs, which prevent you from using the system entirely. It's important to categorize bugs by their severity, so that the worst ones can be fixed first.
Examples of what could constitute a bug
1. The application crashes to code because it doesn't check that a connection is valid before running a stored procedure This is likely covered because it crashes to code
Figure: Yellow screen of death
1. A sum total is negative instead of positive because the wrong operator (plus instead of minus) has been used to calculate the running balance This is likely covered because data is inconsistent with the specified business rules
Figure: An incorrect sum is likely to be a bug
1. The application is missing the Monthly Sales report This is likely covered because the application is missing functionality specified in the specification
2. The output HTML in the application is formatted way out of line and does not display in the specified browser (e.g. Safari) This is likely covered because it is substantially inconsistent with the agreed mockup
Examples of what is not a bug
1. Any problem caused by software or an application not written by the organization supplying the software
2. The customer requirement was not included in the user interface/mock-ups/specifications
3. The client decides that they don't like the look of the current form and wants the buttons at the bottom of the form instead of at the top, even though the form is substantially the same as shown in the specification
4. The original specification states that the total price excludes GST, but it really should have included GST. This is a change to the specification, and is not included in the contract
Using Work Items in Azure DevOps or GitHub
Using a Work Tracking tool allows you to create work items such as user stories, bugs, tasks, test cases etc. Only create bugs for defects, faults, flaws, or imperfections that fulfill your definition of a bug.
For everything else, use other work item types.
Figure: Work item types
Handling additional work for fixed-price contracts
Scrum wasn't designed for "fixed price, fixed scope" contracts. Any new features or modifications (non-bug items) not in the original Sprint or Sprints are classed as additional work and are outside the scope of the contract.
Any tasks which are bugs should be marked as additional items and be completed in the current Sprint if possible. Most importantly, after the Sprint Plan has been sent, a PBI should NOT be entered as an item (additional or otherwise) in ANY Sprints if they are not a bug. Instead, move all non-bug items to the Product Backlog for future review after the warranty period for the fixed price contract has passed.
Handling additional work in a Scrum project
Any new features or modifications (non-bug items) not in the original Product Backlog are classed as additional PBI's and placed on the Product Backlog.
Any tasks which are bugs found during the current Sprint should be fixed within the current Sprint.
Any tasks which are bugs found outside of the current Sprint should be added to the Product Backlog.
Figure: Adding a bug to the Product Backlog in Azure DevOps
See Do you know when to create bugs? and Do you know the 3 steps to a PBI?
Note: The above is our definition. Others have different definitions that we do not subscribe to: Painless Bug Tracking.
Figure: XXX
You can also use the Wiki definition of "Software Bug" as a reference to understand this concept: Wikipedia Definition of Software Bug.
Efficiency - Do you know the quickest way to fix small web errors?
Imagine this scenario... A designer notices a small typo on an intranet page. As a good employee, they open up the backlog and create a PBI to fix the spelling error. Then send a "to myself" to action.
Meanwhile they are thinking... "That took more time to report the error than it would have taken me to fix it".
Small errors should be fixed by the person who found them straight away. Text changes can be easily done in SharePoint, WordPress, or GitHub. The best way to make changes easy is by using TinaCMS.
Bear in mind that communication is indispensable. Therefore, it's crucial to ensure that other individuals connected to that content are informed about the fixes/changes through either an @mention or a brief instant message (IM).
Epecially if you find out who the culprit is, it is a good idea to notify that person including the things you have fixed, so it doesn't happen again.
Figure: XXX
Do you know how to reply to free support requests that takes more than 20 minutes?
If you need more than 20 minutes of work to perform a task, then it's not free, and you need to get approval for it.
Follow this template to reply:
To:
Charlie
Subject:
Request to fix bug
Hi Charlie
If it was a quick 5 mins I would do it straight away. However I need to do a little investigation - maybe a couple of hours.
If that is OK, I will spend that time on this and let you know how I go.
Please approve
Denise
✅ Figure: Good Example - Ask for billable hours approval if a support request demands more than 20 minutes

Do you document "TODO" tasks?

It's common to add a TODO comment to some code you're working on, either because there's more work to be done here or because you've spotted a problem that will need to be fixed later. But how do you ensure these are tracked and followed up?

We add a TODO comment to our code when we have either identified or introduced technical debt as a way of showing other developers that there's work to be done here. It could be finishing the implementation of a feature, or it could be fixing a bug which (hypothetically) is limited in scope and therefore deprioritized. That's all well and good if another developer happens to be looking at that code and sees the comment, but if nobody looks at the code, then the problem could potentially never be fixed.

public class UserService(ApplicationDbContext context) : IUserService
{
    public async Task<UserDto> GetUserByEmailAsync(string emailAddress, CancellationToken cancellationToken = default)
    {
        var dbUser = await context.Users
          .AsNoTracking()
          .FirstOrDefaultAsync(u => u.Email == emailAddress, cancellationToken);

        // TODO: handle null user if not found
        return new UserDto
        {
            Id          = dbUser.Id,
            Name        = dbUser.Name,
            Email       = dbUser.Email,
            TenantId    = dbUser.TenantId.ToString()
        }
    }
}

❌ Figure: Bad example - There is problematic code here, and while the comment is useful as it immediately alerts developers to the problem, but it is not tracked anywhere

Just like with any other technical debt, it's critical to ensure that it is captured on the backlog. When you add a TODO in your code, it should always be accompanied by a link to the PBI.

public class UserService(ApplicationDbContext context) : IUserService
{
    public async Task<UserDto> GetUserByEmailAsync(string emailAddress, CancellationToken cancellationToken = default)
    {
        var dbUser = await context.Users
          .AsNoTracking()
          .FirstOrDefaultAsync(u => u.Email == emailAddress, cancellationToken);

        // TODO: handle null user if not found.
        // https://github.com/Northwind/Northwind.UserManagement/issues/324
        return new UserDto
        {
            Id          = dbUser.Id,
            Name        = dbUser.Name,
            Email       = dbUser.Email,
            TenantId    = dbUser.TenantId.ToString()
        }
    }
}

✅ Figure: Good example - The `TODO` is tracked on the backlog, so the developers and the Product Owner have visibility of the problem and can plan and prioritise accordingly

Tip: If you are reviewing a Pull Request and you spot a TODO without a link to a PBI, you should either create the PBI and update the code (Good Samaritan) or request the change before approving and merging the code.

Do you allow users to get up-to-date messages?
A new version of your software is deployed. How do you tell users important information on older versions?
You shouldn't need to check for updates to be notified of valuable information.
Software is often deployed without any mechanism to insert a message into older versions.
Messages might include notifications to update or simply helpful tips. Eg. Sometimes customers are not aware that their CRM installation is several years old.
Figure: Visual Studio 2019 has helpful notifications to indicate which parts need updating
Do you know the best way to do A/B testing?
A/B Testing is the process of testing different versions of an application on different users to gather empirical evidence to learn which version is better.
Using A/B Testing enables you to get features tested and when used effectively means that a bug will never be deployed to 100% of users. Generally, new features should be tested on 20% of users and rolled out to others once they are reliable.
Video: What is A/B Testing? | Data Science in Minutes
There are several ways this can be done...
Feature Flags (Recommended)
Feature flags are a modern way to toggle features for users. They are essentially a little bit of code that can be turned on and off at will. That means you can choose, when features are deployed and who gets them.
Feature flags are often implemented by developers writing their own code. However, there are better solutions today:
- LaunchDarkly
  - Video interview of LaunchDarkly CEO Edith Harbaugh
- Azure App Configuration is the recommended solution and there are some great tutorials that help developers get up and running in minutes:
  - Use feature filters to enable conditional feature flags
  - Tutorial: Use feature flags in an ASP.NET Core app
Azure Deployment Slots
Azure Deployment Slots are another way of doing A/B testing, you essentially deploy 2 versions of your app and then direct traffic to different versions.
Azure FrontDoor
Azure FrontDoor is an offering that lets developers direct traffic to different versions of an app.

Rules to Better Bug Management and Product Feedback

Do you know the best way to manage product feedback?

UserVoice and UserEcho

Why GitHub is Better

Using GitHub for Feedback Management

More Information - Google Trends

Do you know how to report bugs and give suggestions?

Do you have a clear definition of a bug?

Examples of what could constitute a bug

Examples of what is not a bug

Using Work Items in Azure DevOps or GitHub

Handling additional work for fixed-price contracts

Handling additional work in a Scrum project

Efficiency - Do you know the quickest way to fix small web errors?

Do you know how to reply to free support requests that takes more than 20 minutes?

Hi Charlie

Do you document "TODO" tasks?

Do you allow users to get up-to-date messages?

Do you know the best way to do A/B testing?

Feature Flags (Recommended)

Azure Deployment Slots

Azure FrontDoor