External release notes are well known. It’s the way customers can find out about new updates to the products they use and It can even become a place for the company to show a little personality and brand. Companies like Notion, Slack and Medium are known for the way they use release notes to connect with their customers.
However, behind the external release notes are (often) internal release notes. While these do not get the attention they deserve, they can be a great tool for internal teams to track and communicate changes that have happened to a particular product over its lifespan. When done right, it can save product teams countless hours in answering questions or backtracking changes.
Internal release notes document and communicate changes in order to highlight potential downstream impact to stakeholders. They are not the same as external release notes, differing in the audience, purpose, content and even the timing in which they are published.
While it is no simple task to keep and maintain internal release notes, doing proper due diligence often results in better informed stakeholders and less miscommunication with dependent teams. All this means less meetings and better collaborations with your teams.
Internal V.S External Release Notes (Key differences)
Key differences between internal and external release notes can be evaluated in the following 5 categories: the audience, the purpose, the timing, the channel and the author.
| External | Internal | |
|---|---|---|
| Audience | – Customer – Media outlets | – Dependent teams – Leadership |
| Purpose | – Announce new product features -Notable fixes -Connect with customers | – Alignment with stakeholders – Communication with leadership – Documentation |
| Timing | – At release (as needed) – In line with a marketing initiative | – At or prior to every release |
| Channel | – Public website – In-app – Media channels | – Internal Wiki (Confluence, Gdrive, etc) |
| Author | – Marketing team – Technical writers | – Product manager |
The biggest difference between the two is the audience for whom the release notes are intended for. External release notes are connecting with the public and can even be a way to create buzz around a new release. It often uses simplified language and does not dive deep into the technical aspects of the release. On the contrary, internal release notes are intended for internal teams, stakeholders and leadership. It should be specific enough that dependent teams can understand the potential downstream impact and relevant stakeholders can understand its implications to the product/services offered.
The purpose of these two release notes can also differ. While they both serve to inform on new changes or fixes, external notes can also serve as a way to connect with their users and to enforce the brand voice. On the other hand, internal notes bring visibility, accountability and establish a change log for current and future teams.
When it comes to timing your release notes, external release notes have much more flexibility. Not only can release notes be timed in line with other initiatives (such as marketing or PR initiatives), but you might make a release without a release note at all. Not all changes need to be announced to the public. When it comes to internal notes, it is important that all changes be documented and communicated. So as a rule of thumb, internal release notes are created and shared at (or before) every release.
There are numerous channels for external release notes. In-app notifications, product home page, blogs, social media, and the list goes on. Internal notes are usually limited to internal communication tools such as email, slack or internal blog. The original document should be kept archived in a single place (such as confluence or gdrive).
External release notes can be written by product managers or technical writers, but will often be filtered through the marketing team to make sure that the tone and voice aligns to the brand image. Internal release notes are almost always written by product managers. Sometimes it might be contributed by the tech lead as well.
What Should You Include in an Internal Release Note?
Internal release notes include technical information, links to internal docs, user manuals and an FAQ. It also provides context such as the date, working teams, and the project/feature brief. Ultimately it is a source of truth for change for internal stakeholders to understand downstream impact.
Keeping your release notes structured and easy to read is critical in helping teams actually read the contents inside. What I’ve found works best is to keep all my release notes for a single product in a single document and include an FAQ at the end of each release note. If there are multiple stakeholders that should be addressed specifically, create a section for each and make specific call-outs relevant to each stakeholder.
I’ve included a simple template to help you get started. It covers the basic category of information to include. Download the Internal Release Notes Template
Your team might already have a format for how release notes are written and shared. However, don’t be limited by the status quo. Take the template above and feel free to modify it to better suit your team’s needs.
