GUIDE 2024

Internal Release Notes

As product managers, we work with many stakeholders from many different departments within our organization. Our stakeholders rely on us to inform them on what’s happening with the product, as it impacts their operations and their capabilities. I’ve found that one of the most effective ways to keep stakeholders in the loop is to use internal release notes.

Most of us are familiar with release notes in general. Check out Slack’s release notes as a fantastic example.

Here’s one from March 2018:

The release notes clearly describe what was released and why it was released. These external-facing release notes are targeting external users (and also injects a bit of brand personality and fun).

My philosophy is that you should also create internal release notes for your internal stakeholders.

Why Create Internal Release Notes?

Some might argue that internal release notes are overkill. After all, for those companies that regularly create external-facing release notes, why not just circulate those internally?

Because your internal stakeholders have different sets of needs versus those of your users.

For example, your marketing team needs to know how to position an upcoming change. Your support team needs to know what changes you’re making to their workflows.

While your customer-facing release notes do satisfy some of those needs, they won’t satisfy all of them.

For example, say your customer-facing release notes mention a minor change to how your customers should file bugs. This might only warrant a single bullet point in your external release notes.

However, you probably want your support teams to fully understand how that bug filing process changed so that they’re ready to support it ahead of time and can seamlessly guide users to use the new process correctly. Therefore, you need to provide more detail to internal stakeholders so that they’re informed and prepared.

And for those companies that don’t yet have external release notes, why bother creating internal release notes at all?

You’ll want to have an internal running log of what has been shipped and when. Even if you’re working in a small organization, this historical log can prove to be incredibly valuable over time.

I’ve saved my teams countless hours of debate over when a particular feature was released. I’ve also saved my teams countless hours of debate on whether a particular feature was ever released at all.

And all I had to do was maintain internal release notes!
Join PMHQ

How to Create Internal Release Notes

I’ve found that the most effective way to create and maintain release notes is to have a single running document that has one section for each release date. All you have to do is add a section for each new release. That way, all of the release notes are centralized in one place for consumption.

I used Google Docs for my release notes, but you could easily use Confluence, OneNote, email, or any other to communicate internally.

When creating internal release notes, identify who the consumers are.

For large or decentralized product organizations, your release notes might be targeted at updating your entire product team, so that they’re aware of potential dependencies. For internal product users (such as call centers, customer support, etc.), your release notes might need to address the changes that were made, and how to best navigate them versus their previous state.

From there, organize your release notes based on what your audience likely cares about the most. To use our examples from before: your product organization probably cares the most about changes with high likelihoods of dependencies or regressions. Your internal operations team probably cares the most about any changes to flow or any additions or losses in functionality.

Since I was working with two large operational stakeholders, I broke out my release notes into three sections: 1) new features that would impact them, 2) bugfixes that would impact them, and 3) new features that would not impact them immediately, but that they still needed to be aware of.

Note that I purposely excluded bugfixes that would not impact the operations teams, and I also excluded deeply technical work that we completed (e.g. code refactoring, test suites). The goal here isn’t to brag or claim credit for what your team shipped – it’s to provide helpful and relevant information to the stakeholders.

I prioritized my release notes so that the first item was the most impactful within the category. I also color-coded the different bullet points by stakeholder, so that our different operations teams could quickly filter down to the relevant points.

When creating internal release notes, send them out on a predetermined cadence.

I created release notes on a biweekly basis, since that was our sprint duration, and therefore also our release timings. Since I could match sprints to releases, I used sprint reports as an input for my release notes. Furthermore, I aggregated related small fixes into one cohesive story, or I broke down an epic into more digestible subcomponents.

My particular audience needed to know exactly what got changed in the product, and why.

Therefore, each point of my notes had a screenshot that highlighted what got changed, the rationale behind making the change, and the JIRA tickets associated with the change.

For especially complex changes, I pulled together videos to show how the interaction or flow had changed.

Takeaways

Honestly, it takes time to craft thoughtful release notes – I needed about 2 hours per release to compile this set of artifacts.

Funnily enough, however, by creating internal release notes, I wound up becoming more productive and had fewer meetings to attend over time.

This was due to the fact that I was keeping stakeholders up-to-date, and that we had fewer misunderstandings about what got released and what was not yet released.

For my stakeholders, they also wound up more productive – they no longer needed to conduct large trainings or sessions, and could instead point to the release notes as a constantly-updated source of truth for their teams.

I highly recommend internal release notes when your product impacts your internal departments. Even if your product is mostly customer-facing, you’ll still find value when creating a companion set of internal release notes, as you’ll need to ensure your support teams, operations teams, marketing teams, and sales teams can keep up with the changes that you’ve released.


Have thoughts that you’d like to contribute around internal release notes? Chat with other product leaders around the world in our PMHQ Community!

Clement Kao
Clement Kao
Clement Kao is Co-Founder of Product Manager HQ. He was previously a Principal Product Manager at Blend, an enterprise technology company that is inventing a simpler and more transparent consumer lending experience while ensuring broader access for all types of borrowers.