Why you should include bug fixes in product updates (with templates)

What's the best way to share small improvements, without making updates too noisy?

Sep 25, 2024

Sep 25, 2024

/

0 min read

I recently saw a debate in a product marketing community that got me fired up โ€“ should you share smaller product updates and bugs? For folks who recommend skipping bugs, there were two common threads:

  1. Itโ€™s a lot of work for low value. Fixing bugs doesnโ€™t directly grow the business, so it was less important than time spent getting new revenue.

  2. Sharing bugs is risky strategically, because customers can use them against you in renewal negotiations. If you put a spotlight on these issues, the downside is too great.

If you work in marketing or sales, these may seem logical. It makes sense to focus on measurable business impact and not get sucked into the weeds of routine product changes.

If your reaction is horror, you probably work with customers or in product development.

Regardless of which side youโ€™re starting on, letโ€™s talk about how to message smaller updates in your releases. And why bugs are actually an important part of healthy customer relationships. Done well, they can even be a selling point for prospects.

Myth #1: Talking about bugs hurts your business

You may believe that by admitting you fixed an issue, it gives your customers leverage they can use against you in renewals or other negotiations. As a repeat startup founder, I've spent over a decade working with thousands of customers of all sizes (including new business and renewals) โ€“ hereโ€™s why you donโ€™t need to worry about bug transparency hurting your business:

  1. Customers donโ€™t need release notes to discover the types of bugs that affect renewals. These are people who use your product regularly โ€” they already know and have the support tickets to prove it. Customers are busy and donโ€™t have the time or attention to keep score of bugs with zero impact on their day.*

  2. Hiding any mention of bugs will raise more questions that it avoids. Customers are smart. You donโ€™t need to chronicle every single typo and passing issue, but a steady stream of bugs squashed is a sign of quality and good for growing long term customer relationships.

Aside from practical issues, it can also be part of the contract negotiation process. Especially if you work with Enterprise customers, they expect you have process to communicate issues. This is why things like system status pages are a hard requirement. Some will also require proactive disclosure of critical issues as part of their contract's service level agreement (SLA), including documenting "Known issues" or severity of certain bugs which could affect their account.

*Note: I have seen cases where procurement teams will ask their buyer if there are any bugs impacting their account going into a renewal โ€“ but again, these are issues with firsthand impact and not discovered because of a changelog.

Myth #2: Sharing small updates like bug fixes isn't worth the effort

Another common reason for skipping small updates like bug fixes is they donโ€™t feel very valuable or strategic. Why spend time collecting a few bugs to include when you have more valuable work which will actually grow the business? If you're feeling this tension, let's reframe the goal.

I love working on valuable things too, but often this excuse appears when effort required feels out of sync with the results. When getting updates is high effort, you will compare it to other things which are also high effort โ€” preparing for tier one releases, updating product enablement, etc. Compared to those things, it seems silly to waste time collecting tiny updates. But what if you lowered the effort required?

If sharing small updates feels hard, thatโ€™s the first problem to solve. The real issue is often finding a cadence which your team can support, and avoid chasing down updates from other teams. The goal here is not busy work, but to develop a process which will make including a few small updates easy for the people responsible.

Why is this important? The long tail! Small things add up (see Githubโ€™s Project Paper Cuts), and the complete absence of incremental improvements is noticeable. And if you can develop a strong voice, or be funny in the process? Tiny updates can even become a brand asset.

As you'll see in a later section, some bugs are actually improvements with the right positioning. But first, let's explore a framework you can use to structure, and publish product release notes with less effort.

How to include bugs in release notes (a framework)

Not every product improvement should get a spotlight when shipped. But they still need communication, even if it's not a big marketing fanfare. This is where bundling announcements into weekly or seasonal product releases can help you tell the right story.

In this approach, you lead with a headline feature (think: โ€œTier 1 or 2โ€) and then include bugs or minor updates afterwards. This is also easier for customers to digest, because they arenโ€™t going to read your blog daily. Discovering the latest updates needs to be easy, because you are ONE of many vendors asking for your customer's attention.

For weekly or monthly release roundups, there are typically three buckets of updates:

  1. Added / Improved / Fixed (Recommended)

  2. Features / Improvements / Bug fixes

The first example focuses on the results (what it means for you), the second categorizes by describing which type of update. It's a subtle difference, but I favor #1 because it matches how a typical person would talk about the release. Framerโ€™s monthly updates follow this format.

Should you mention bugs in product videos?

If you also record regular product release videos to demo new features, don't highlight each bug or minor improvement individually. Instead, focus on describing the product areas where you improved the overall experience.

Example Narrative: "We've made a number of changes and addressed issues which improve the [PRODUCT AREA] experienceโ€ฆ"

Always bundle your bugs

Bugs should always be part of a larger release or batched together. Features and most improvements can get their own release notes, but bugs are different. The only time you should proactively push standalone bug fixes with customers is if they were impacted and actively dealing with the issue. Availability ("uptime") issues are separate, and belong on a system status page instead of release notes.

Bug fixes are a natural complement to "Quality of life" improvements. Bundling both together into a roundup gives you plenty of room to tell a positive story of progress. Recording a product update video with highlights from both can make sure that you're introducing these with the right tone (think: "We also have some crowd pleasers in the latest releaseโ€ฆ") and tempo.

Bundling bugs and minor improvements also works well for weekly/monthly roundup emails with limited space. Focus on 2-3 highlights in the email, and include a link to "a dozen other improvements and fixes shipped this month" where they can see the rest.

Is it really a bug?

Some bugs are upgrades in disguise, a positioning example

Some โ€œbugsโ€ are improvements in disguise, and an opportunity to flex your positioning muscle. Here's an example of two ways to describe the same update:

  1. Bug: Fixed issue where emoji were removed from titles when publishing.

  2. Improvement:  You can now use emoji in titles. ๐ŸŽ‰

The second example would have a better chance of customers discovering it. Just because engineering considered something a bugfix, doesn't mean that's how you should message it. Some bugs are better phrased as improvements when communicating to customers. Just donโ€™t do it for every bug or youโ€™ll venture into propaganda, and erode credibility.

Templates for sharing bug fixes

When writing release notes for bugs, there's no need to get creative with explanations like with new features. Each should be a single sentence, and follow the same format. It should repetitive, but clear. Use a bulleted list, because the number of bugs doesn't matter.

The templates below will work for documenting any bug โ€” pick one that feels most comfortable and stick with it:

Template #1

Fixed issue where [ACTION] would [BUGGY RESULT]

"Fixed issue where uploading a PNG would prevent you from publishing changes."

Template #2

[ACTION] now [CORRECT RESULT]

"Uploading a PNG now allows you to publish changes."

Template #3

[ACTION] will no longer [BUGGY RESULT]

"Uploading a PNG will no longer prevent you from publishing changes."

If youโ€™re familiar with the engineering process, you might get release notes based on โ€œmerged pull requestsโ€ or a ledger of specific changes merged into the codebase. Itโ€™s OK to curate โ€“ just because engineering considers two things separate bugs, you can still decide to combine similar bugs together in release notes for clarity.

Bugs happen, so learning to talk about them openly as part of your product comms is a great skill to build. These approaches are a safe place to start as you discover your own cadence.

We also have tips for writing new feature announcements, or you can continue with how to communicate a feature removal.

I recently saw a debate in a product marketing community that got me fired up โ€“ should you share smaller product updates and bugs? For folks who recommend skipping bugs, there were two common threads:

  1. Itโ€™s a lot of work for low value. Fixing bugs doesnโ€™t directly grow the business, so it was less important than time spent getting new revenue.

  2. Sharing bugs is risky strategically, because customers can use them against you in renewal negotiations. If you put a spotlight on these issues, the downside is too great.

If you work in marketing or sales, these may seem logical. It makes sense to focus on measurable business impact and not get sucked into the weeds of routine product changes.

If your reaction is horror, you probably work with customers or in product development.

Regardless of which side youโ€™re starting on, letโ€™s talk about how to message smaller updates in your releases. And why bugs are actually an important part of healthy customer relationships. Done well, they can even be a selling point for prospects.

Myth #1: Talking about bugs hurts your business

You may believe that by admitting you fixed an issue, it gives your customers leverage they can use against you in renewals or other negotiations. As a repeat startup founder, I've spent over a decade working with thousands of customers of all sizes (including new business and renewals) โ€“ hereโ€™s why you donโ€™t need to worry about bug transparency hurting your business:

  1. Customers donโ€™t need release notes to discover the types of bugs that affect renewals. These are people who use your product regularly โ€” they already know and have the support tickets to prove it. Customers are busy and donโ€™t have the time or attention to keep score of bugs with zero impact on their day.*

  2. Hiding any mention of bugs will raise more questions that it avoids. Customers are smart. You donโ€™t need to chronicle every single typo and passing issue, but a steady stream of bugs squashed is a sign of quality and good for growing long term customer relationships.

Aside from practical issues, it can also be part of the contract negotiation process. Especially if you work with Enterprise customers, they expect you have process to communicate issues. This is why things like system status pages are a hard requirement. Some will also require proactive disclosure of critical issues as part of their contract's service level agreement (SLA), including documenting "Known issues" or severity of certain bugs which could affect their account.

*Note: I have seen cases where procurement teams will ask their buyer if there are any bugs impacting their account going into a renewal โ€“ but again, these are issues with firsthand impact and not discovered because of a changelog.

Myth #2: Sharing small updates like bug fixes isn't worth the effort

Another common reason for skipping small updates like bug fixes is they donโ€™t feel very valuable or strategic. Why spend time collecting a few bugs to include when you have more valuable work which will actually grow the business? If you're feeling this tension, let's reframe the goal.

I love working on valuable things too, but often this excuse appears when effort required feels out of sync with the results. When getting updates is high effort, you will compare it to other things which are also high effort โ€” preparing for tier one releases, updating product enablement, etc. Compared to those things, it seems silly to waste time collecting tiny updates. But what if you lowered the effort required?

If sharing small updates feels hard, thatโ€™s the first problem to solve. The real issue is often finding a cadence which your team can support, and avoid chasing down updates from other teams. The goal here is not busy work, but to develop a process which will make including a few small updates easy for the people responsible.

Why is this important? The long tail! Small things add up (see Githubโ€™s Project Paper Cuts), and the complete absence of incremental improvements is noticeable. And if you can develop a strong voice, or be funny in the process? Tiny updates can even become a brand asset.

As you'll see in a later section, some bugs are actually improvements with the right positioning. But first, let's explore a framework you can use to structure, and publish product release notes with less effort.

How to include bugs in release notes (a framework)

Not every product improvement should get a spotlight when shipped. But they still need communication, even if it's not a big marketing fanfare. This is where bundling announcements into weekly or seasonal product releases can help you tell the right story.

In this approach, you lead with a headline feature (think: โ€œTier 1 or 2โ€) and then include bugs or minor updates afterwards. This is also easier for customers to digest, because they arenโ€™t going to read your blog daily. Discovering the latest updates needs to be easy, because you are ONE of many vendors asking for your customer's attention.

For weekly or monthly release roundups, there are typically three buckets of updates:

  1. Added / Improved / Fixed (Recommended)

  2. Features / Improvements / Bug fixes

The first example focuses on the results (what it means for you), the second categorizes by describing which type of update. It's a subtle difference, but I favor #1 because it matches how a typical person would talk about the release. Framerโ€™s monthly updates follow this format.

Should you mention bugs in product videos?

If you also record regular product release videos to demo new features, don't highlight each bug or minor improvement individually. Instead, focus on describing the product areas where you improved the overall experience.

Example Narrative: "We've made a number of changes and addressed issues which improve the [PRODUCT AREA] experienceโ€ฆ"

Always bundle your bugs

Bugs should always be part of a larger release or batched together. Features and most improvements can get their own release notes, but bugs are different. The only time you should proactively push standalone bug fixes with customers is if they were impacted and actively dealing with the issue. Availability ("uptime") issues are separate, and belong on a system status page instead of release notes.

Bug fixes are a natural complement to "Quality of life" improvements. Bundling both together into a roundup gives you plenty of room to tell a positive story of progress. Recording a product update video with highlights from both can make sure that you're introducing these with the right tone (think: "We also have some crowd pleasers in the latest releaseโ€ฆ") and tempo.

Bundling bugs and minor improvements also works well for weekly/monthly roundup emails with limited space. Focus on 2-3 highlights in the email, and include a link to "a dozen other improvements and fixes shipped this month" where they can see the rest.

Is it really a bug?

Some bugs are upgrades in disguise, a positioning example

Some โ€œbugsโ€ are improvements in disguise, and an opportunity to flex your positioning muscle. Here's an example of two ways to describe the same update:

  1. Bug: Fixed issue where emoji were removed from titles when publishing.

  2. Improvement:  You can now use emoji in titles. ๐ŸŽ‰

The second example would have a better chance of customers discovering it. Just because engineering considered something a bugfix, doesn't mean that's how you should message it. Some bugs are better phrased as improvements when communicating to customers. Just donโ€™t do it for every bug or youโ€™ll venture into propaganda, and erode credibility.

Templates for sharing bug fixes

When writing release notes for bugs, there's no need to get creative with explanations like with new features. Each should be a single sentence, and follow the same format. It should repetitive, but clear. Use a bulleted list, because the number of bugs doesn't matter.

The templates below will work for documenting any bug โ€” pick one that feels most comfortable and stick with it:

Template #1

Fixed issue where [ACTION] would [BUGGY RESULT]

"Fixed issue where uploading a PNG would prevent you from publishing changes."

Template #2

[ACTION] now [CORRECT RESULT]

"Uploading a PNG now allows you to publish changes."

Template #3

[ACTION] will no longer [BUGGY RESULT]

"Uploading a PNG will no longer prevent you from publishing changes."

If youโ€™re familiar with the engineering process, you might get release notes based on โ€œmerged pull requestsโ€ or a ledger of specific changes merged into the codebase. Itโ€™s OK to curate โ€“ just because engineering considers two things separate bugs, you can still decide to combine similar bugs together in release notes for clarity.

Bugs happen, so learning to talk about them openly as part of your product comms is a great skill to build. These approaches are a safe place to start as you discover your own cadence.

We also have tips for writing new feature announcements, or you can continue with how to communicate a feature removal.

I recently saw a debate in a product marketing community that got me fired up โ€“ should you share smaller product updates and bugs? For folks who recommend skipping bugs, there were two common threads:

  1. Itโ€™s a lot of work for low value. Fixing bugs doesnโ€™t directly grow the business, so it was less important than time spent getting new revenue.

  2. Sharing bugs is risky strategically, because customers can use them against you in renewal negotiations. If you put a spotlight on these issues, the downside is too great.

If you work in marketing or sales, these may seem logical. It makes sense to focus on measurable business impact and not get sucked into the weeds of routine product changes.

If your reaction is horror, you probably work with customers or in product development.

Regardless of which side youโ€™re starting on, letโ€™s talk about how to message smaller updates in your releases. And why bugs are actually an important part of healthy customer relationships. Done well, they can even be a selling point for prospects.

Myth #1: Talking about bugs hurts your business

You may believe that by admitting you fixed an issue, it gives your customers leverage they can use against you in renewals or other negotiations. As a repeat startup founder, I've spent over a decade working with thousands of customers of all sizes (including new business and renewals) โ€“ hereโ€™s why you donโ€™t need to worry about bug transparency hurting your business:

  1. Customers donโ€™t need release notes to discover the types of bugs that affect renewals. These are people who use your product regularly โ€” they already know and have the support tickets to prove it. Customers are busy and donโ€™t have the time or attention to keep score of bugs with zero impact on their day.*

  2. Hiding any mention of bugs will raise more questions that it avoids. Customers are smart. You donโ€™t need to chronicle every single typo and passing issue, but a steady stream of bugs squashed is a sign of quality and good for growing long term customer relationships.

Aside from practical issues, it can also be part of the contract negotiation process. Especially if you work with Enterprise customers, they expect you have process to communicate issues. This is why things like system status pages are a hard requirement. Some will also require proactive disclosure of critical issues as part of their contract's service level agreement (SLA), including documenting "Known issues" or severity of certain bugs which could affect their account.

*Note: I have seen cases where procurement teams will ask their buyer if there are any bugs impacting their account going into a renewal โ€“ but again, these are issues with firsthand impact and not discovered because of a changelog.

Myth #2: Sharing small updates like bug fixes isn't worth the effort

Another common reason for skipping small updates like bug fixes is they donโ€™t feel very valuable or strategic. Why spend time collecting a few bugs to include when you have more valuable work which will actually grow the business? If you're feeling this tension, let's reframe the goal.

I love working on valuable things too, but often this excuse appears when effort required feels out of sync with the results. When getting updates is high effort, you will compare it to other things which are also high effort โ€” preparing for tier one releases, updating product enablement, etc. Compared to those things, it seems silly to waste time collecting tiny updates. But what if you lowered the effort required?

If sharing small updates feels hard, thatโ€™s the first problem to solve. The real issue is often finding a cadence which your team can support, and avoid chasing down updates from other teams. The goal here is not busy work, but to develop a process which will make including a few small updates easy for the people responsible.

Why is this important? The long tail! Small things add up (see Githubโ€™s Project Paper Cuts), and the complete absence of incremental improvements is noticeable. And if you can develop a strong voice, or be funny in the process? Tiny updates can even become a brand asset.

As you'll see in a later section, some bugs are actually improvements with the right positioning. But first, let's explore a framework you can use to structure, and publish product release notes with less effort.

How to include bugs in release notes (a framework)

Not every product improvement should get a spotlight when shipped. But they still need communication, even if it's not a big marketing fanfare. This is where bundling announcements into weekly or seasonal product releases can help you tell the right story.

In this approach, you lead with a headline feature (think: โ€œTier 1 or 2โ€) and then include bugs or minor updates afterwards. This is also easier for customers to digest, because they arenโ€™t going to read your blog daily. Discovering the latest updates needs to be easy, because you are ONE of many vendors asking for your customer's attention.

For weekly or monthly release roundups, there are typically three buckets of updates:

  1. Added / Improved / Fixed (Recommended)

  2. Features / Improvements / Bug fixes

The first example focuses on the results (what it means for you), the second categorizes by describing which type of update. It's a subtle difference, but I favor #1 because it matches how a typical person would talk about the release. Framerโ€™s monthly updates follow this format.

Should you mention bugs in product videos?

If you also record regular product release videos to demo new features, don't highlight each bug or minor improvement individually. Instead, focus on describing the product areas where you improved the overall experience.

Example Narrative: "We've made a number of changes and addressed issues which improve the [PRODUCT AREA] experienceโ€ฆ"

Always bundle your bugs

Bugs should always be part of a larger release or batched together. Features and most improvements can get their own release notes, but bugs are different. The only time you should proactively push standalone bug fixes with customers is if they were impacted and actively dealing with the issue. Availability ("uptime") issues are separate, and belong on a system status page instead of release notes.

Bug fixes are a natural complement to "Quality of life" improvements. Bundling both together into a roundup gives you plenty of room to tell a positive story of progress. Recording a product update video with highlights from both can make sure that you're introducing these with the right tone (think: "We also have some crowd pleasers in the latest releaseโ€ฆ") and tempo.

Bundling bugs and minor improvements also works well for weekly/monthly roundup emails with limited space. Focus on 2-3 highlights in the email, and include a link to "a dozen other improvements and fixes shipped this month" where they can see the rest.

Is it really a bug?

Some bugs are upgrades in disguise, a positioning example

Some โ€œbugsโ€ are improvements in disguise, and an opportunity to flex your positioning muscle. Here's an example of two ways to describe the same update:

  1. Bug: Fixed issue where emoji were removed from titles when publishing.

  2. Improvement:  You can now use emoji in titles. ๐ŸŽ‰

The second example would have a better chance of customers discovering it. Just because engineering considered something a bugfix, doesn't mean that's how you should message it. Some bugs are better phrased as improvements when communicating to customers. Just donโ€™t do it for every bug or youโ€™ll venture into propaganda, and erode credibility.

Templates for sharing bug fixes

When writing release notes for bugs, there's no need to get creative with explanations like with new features. Each should be a single sentence, and follow the same format. It should repetitive, but clear. Use a bulleted list, because the number of bugs doesn't matter.

The templates below will work for documenting any bug โ€” pick one that feels most comfortable and stick with it:

Template #1

Fixed issue where [ACTION] would [BUGGY RESULT]

"Fixed issue where uploading a PNG would prevent you from publishing changes."

Template #2

[ACTION] now [CORRECT RESULT]

"Uploading a PNG now allows you to publish changes."

Template #3

[ACTION] will no longer [BUGGY RESULT]

"Uploading a PNG will no longer prevent you from publishing changes."

If youโ€™re familiar with the engineering process, you might get release notes based on โ€œmerged pull requestsโ€ or a ledger of specific changes merged into the codebase. Itโ€™s OK to curate โ€“ just because engineering considers two things separate bugs, you can still decide to combine similar bugs together in release notes for clarity.

Bugs happen, so learning to talk about them openly as part of your product comms is a great skill to build. These approaches are a safe place to start as you discover your own cadence.

We also have tips for writing new feature announcements, or you can continue with how to communicate a feature removal.

Need to tell a better product story?

Learn how Rally makes great storytelling easy for your whole team, sales to customer.