Use Knowledge Management to Create Release Notes Templates and Streamline Your Product Delivery Process

Fact: Product release communication is problematic

The purpose of product release notes is to let your internal teams (from engineering to customer support) and your external stakeholders (customers and partners) know there have been changes to the product. In tech, where everything moves at light speed, delivering product updates via release notes is practically an age-old problem.

Every company at which I’ve worked has struggled to get release notes “right.” But it’s a hard thing to get right; the importance of every change or product launch will vary based on the audience, how that change alters a particular group’s interaction with the feature, and how that group uses the overall product everyday.

These product release communications (commonly known as release notes) need to be delivered to audiences who care about different things. As a Revenue Empowerment leader at Guru, my constituents are anyone whose ability to do their job is impacted by the product roadmap, including:

• The Product/Design/Engineering teams
• The Sales Team (Sales ops, Inside sales, Account Executives across segments)
• Customer Experience (Success Managers and Support reps)
• Marketing Team (Product Marketing, Growth Marketing, Brand, Content who will lead the GTM strategy and press outreach for the product)
• Business Development and Partners

All of these partners have to digest product updates and immediately figure out to what degree they need to apply those updates to their jobs. They also need to consider how they can help end users understand the impact any change will have on them.

The person (or team) crafting the release communications need to consider all of the audiences who will consume the product knowledge. What are the implications of the release for a backend engineer vs. a prospective customer in the retail industry?

How Not to Approach Release Notes

While it’s hard to take into account the needs of different audiences, it’s also simply not scalable for a Product Manager or a Product Marketing Manager (PMM) to write five different versions of internal release notes. In my experience, release notes are either too long and out of context or don’t have enough technical chops. Static release notes don’t give us this insight and are often written for the author, not the person who needs to understand what’s changed. Quite frankly, they’re usually missed opportunities.  

I’ve sat through hour-long, weekly release note calls on which a monotone voice from product management talks through bullet points on slides. After the call ends, that same product manager receives emails, phone calls (remember those?), Slacks, etc., from everyone from customer support to sales who want to know what the changes mean for them, their customers, and prospects. If you missed the call, you missed nuance and context, and instead just got the raw changelog.

But it’s not the role of the product manager to do this sacred translation; it’s their job to build a product that solves a problem for the market. It's the job of the PMM to translate that intent so that the market understands its value.

The secret to writing great software release notes

I am a big Sound of Music fan (shocking, I know) and as an enablement professional, the timeless lessons in the movie ring true. “Let’s start at the very beginning/it’s a very good place to start,” goes through my head on a weekly basis. So, in shaping or reshaping a product delivery process, you have to learn the language before you can teach the subject.

1. Develop an internal glossary

The first step of digging into this process means getting the entire team speaking the same language. Socializing shared terminology seems obvious, but it might not be happening across your organization. Not knowing acronyms and misunderstanding language can be isolating, creating confusion and silos across teams.

Example: Our marketing team uses the term “launch” to describe when and how we’re going to market with a feature. The engineering team however, uses the word “launch” to describe when a feature has been released to our staging environment. The feature specific launch is “finished” for engineering before our customers know about it. This was confusing and internally conflicting.

No one wants to be the one to speak up publicly admitting that they don’t know what something means silly by asking for definitions. Our solution: In a cross-functional working group (with representation from engineering, product, product marketing), we fleshed out the nuance and documented our product release definitions:

Note: If any of the Cards fail to load, just refresh the page!

2. What to include in your release notes

After a shared language is established and your team is able to articulate the release terminology, you can write your notes. The easiest thing to do is to create a reusable template for writing release notes. This way, stakeholders become familiar with the format after a few iterations, and saves you the trouble of having to reinvent the wheel each time.

At a minimum, good release notes include:

• The release date(s)
• Internal and external
• A description of the feature or bug
• The product(s) being impacted (if you have more than one)
• If you have multiple software products, you may also want to include version numbers
• Where questions can be asked internally

Great release notes, however, also include:

• Anticipated frequently asked questions (FAQs)
• Link to new public documentation, if available
• For features:
• The name of the feature
• Screenshots of what the feature looks like
• Video of how to demo the feature
• Why the feature exists
• How it impacts relevant buyer/customer personas

Here’s the template we use internally (feel free to copy!):

💡Note: It’s helpful to assign directly responsible individuals for this task (rather than leaving it up to a group effort where no one owns it). Engineering or Product Managers should own the technical side of the notes (name/version/product/dates/screenshots), while Product Marketing Managers or Sales Engineers should own the contextual information (buyer personas/why it matters).

Implementing a product delivery process strategy

Create a consistent communication format

Now that you’ve unified the terminology and written your template, the next step is to agree upon a consistent delivery medium (ie: Slack, email, Loom, Guru, Google Docs) and methodology. A consistent delivery medium ensures your release note constituents know where they should go or look or subscribe (to pull) to be aware of a release.

This is also essential for change management because you generally have to tell someone something multiple times to ensure they fully absorb it. Depending on the type of release, the changes to the UI/UX (user interface and user experience), and the impact to the customer, your release note audience will need to be pushed product knowledge (to push). At Guru we employ both push and pull methodologies.

The Pull: Where to find knowledge

For us, stakeholders can follow in our Slack #release-notes channel, where there’s a consistent and digestible format for everything from bug fixes to net-new features. Keep in mind that your respective audiences not only have to be aware that the releases are happening (via the pull in Slack or email) but more importantly, they need to know why that release matters in context.

The knowledge that a release simply will happen or has happened isn’t valuable unless your team can actually do something with it. In order to develop a consistent format that would provide appropriate context, I surveyed sales reps, account development reps, business development folks (the works), to establish our template for product delivery we call the “Feature Breakdown Card”, which you can find above.

When an Engineering Manager begins development on a new feature, directly responsible individuals are alerted via Asana to create the feature-specific Feature Breakdown Card using the release notes template. The new Feature Breakdown card becomes the robust, single source of truth or the “brain of feature” we’re releasing. Subject matter experts (SME) — such as PMM and sales engineers — include details on why the release is valuable, for whom it matters most, and where applicable, guidance on how to demo the feature as part of a larger story.

The release notes stakeholders, particularly Account Executives, return to the same cards again and again because they’ve learned that the dynamic knowledge on the Feature Breakdown Card is trusted, relevant, and applicable. Audiences are now both speaking the same language and reading from the same (dynamic) playbook. A return to the Feature Breakdown Card is still part of a “pull” method because it is self-paced, and done to prep for a sales or support call, or if a prospect has a question about the roadmap.

The Push: Proactively providing knowledge

The Push method comes into play when knowledge about a release is time-sensitive, and critical for specific teams. Here, this is accomplished through Guru’s announcements functionality. Based on the impact to my internal audiences, I push an announcement via Guru to a relevant group. I can then see a report of those who’ve acknowledged or read the alert and publicly shame remind those who haven’t.  

Why a knowledge-driven culture is the key 🗝

Despite all of the above, it’s not actually as simple as agreeing on terminology, writing killer release notes, and creating a mechanism for dynamic product delivery. Teams need to be able to collaborate on knowledge and give feedback over time. Providing feedback and improving knowledge by sharing it is part of the roles and responsibilities of everyone on the team.

For us, that means that when knowledge consumers (in this case, release note stakeholders) have a question or learn something new, they comment on the Feature Breakdown Card. We also incorporate questions asked and answered in Slack by commenting as a way to continuously improve knowledge. The subject matter expert (typically the PMM) will review and incorporate that new knowledge or relevant question, putting it into context in the particular Feature Breakdown card.

We also make all of our release notes easily accessible by putting them in either the upcoming or launched sections of our Feature Breakdown Board, where they can be further organized internally. That way, they’re easy to follow at a glance. If you’re not using Guru, we recommend trying to create a release notes page, or linked changelog.

As with any other process, this one is constantly evolving. Product delivery and release notes are never as simple as one-and-done. As the needs of your business change, your process, responsibilities, and templates should change with them. But by striving for easy understanding, context, and usability, you can’t lose.