Difference between release notes, what’s new, newsletter, and changelog
Every software product has a life cycle. And somewhere between the development and maintenance phases appears the need to communicate the changes made in the product. Namely, what are the new and updated features, coming-soon enhancements, bug fixes, etc.
Every update in a product needs some type of internal or external communication. In this article, we will look at 4 common doc types for announcing product changes: release notes, what’s new, a newsletter, and a changelog. We can collectively call them “docs” for now.
Most likely, you have heard, used, or read these docs before, but can you tell what is the exact difference between them?
There should be some kind of distinction; otherwise, why would we have 4 different names, right?
Well, it’s time to figure it out by looking from different angles. Let’s explore the purpose, target audience, format, distribution channels, and creators of these doc types.
A few disclaimers before we start:
- Each project has its own peculiarities, processes, and naming conventions. One of the issues I have faced is improper naming. For example, some people use the terms “release notes” and “changelog” interchangeably. Or even worse, not knowing how they differ, people mix those two doc types into one Frankenstein. So, sometimes the problem is in the lack of knowledge, sometimes — in improper naming, and sometimes — both.
- Each project has its own peculiarities, processes, and naming conventions. So, further, I’ll describe my own experience and beliefs. That’s why I will be using the words “usually” and “typically” a lot. If you have the opposite experience, please comment on this article: it will be super-interesting to compare and see how other teams work.
And now, let’s start with release notes.
Release notes
Release notes (further RN) are documents that accompany software releases. This type of documentation provides general information about the changes, like new and updated features (also called enhancements and improvements), major bug fixes, and known issues of the current product version.
By “major” bug fixes, I mean that not all the bug fixes should be described in RN — only bugs considered as important, found on the prod environment, the ones that the users may already know about. For example, you can describe only the bugs that have “introduced “ and “external” labels in Jira tickets. Listing all the bug fixes will make it look like your product has too many problems.
To put it simply, RN are notes about the current release. But what some people don’t know is that traditionally RN should not contain detailed step-by-step instructions or ticket numbers. Keep comprehensive, detailed instructions for user guides and ticket numbers — for changelogs. Meanwhile, the links to the relevant user guides and instructions are more than welcome. Sometimes there is even an additional section at the bottom of the RN called “Related items”, which contains a bulleted list of the links to additional help materials. By the way, RN are not only about text; adding screenshots is a common practice as well.
Typically, release notes are targeted towards the product users and the company’s customers and partners. RN serve to keep them updated on the product enhancements, provoke their interest in the new features, and demonstrate commitment to continuous improvement. A tip here: avoid marketing content in RN; there is no need to resell the app to a paying customer.
It makes sense to provide release notes only if there is something to talk about (concrete features and bugs); otherwise — the changelog is enough.
As for the distribution channels, RN are often published on the product’s website, documentation portal, or support center. Sometimes RN pop up automatically after we update an application. They can also be emailed to the users or included in the product’s installation package. Actually, there are no limitations to the ways of distributing release notes.
Here is an example of an online release notes structure.
Note that there is no single standardized RN format. Companies and projects adopt their own formatting styles based on the peculiarities of their product, frequency of the releases, corporate brand books, the needed output format, and even personal preferences. That’s why, sadly, on some projects, there is no clear division between RN, changelog, and what’s new. Though personally I, as a Technical Communicator, think there should be.
What’s new
What’s new is also a brief description, an overview of new and updated features. And sometimes, there is a fine line between RN and what’s new. Yet the line does exist.
First of all, what’s new usually does not contain a description of bug fixes. Second of all, what’s new is shorter. Unlike RN, what’s new provides a more concise and user-friendly overview of the most important or recent changes that are supposed to be exciting.
What’s new is usually written for nontechnical users, such as users, customers, and business partners, who want to know the benefits and value of the changes and how they can use them to achieve their goals.
On my current project, what’s new is a simple pop-up window that appears on the screen after a person opens up a certain page or tab. Such pop-up contains 2–4 short sentences about 1 new feature and a “read more” button leading to the help documentation. This is it, just a few words and an invitation to read more. So, the target audience in this particular case is narrowed down to the product end users only.
Basically, what’s new highlights the latest improvements and enhancements that users could like (or at least should be aware of). Oftentimes, the what’s new sections are found embedded into software applications, websites, or platforms. They can also be presented as a web page, a video, a blog post, or even shared via social media and other marketing channels.
Newsletter
I guess originally, newsletters were news sent as paper letters via a post office. Or maybe not — who knows. Anyway, nowadays newsletters are periodic publications distributed to subscribers via email campaigns. Such info can be sent not only externally (to the customers, for example), but also internally (to the employees).
You can think of newsletters as of online magazines, or newspapers, or advertisements in those magazines. If your email address is on the subscribers’ list, you receive regular newsletters.
What’s interesting here is that you can find release notes sent by email too. But you are unlikely to find a newsletter published on a documentation portal.
Another distinction is the creator. Newsletters are usually created by the Customer Support team, whereas release notes are written by Technical Writers.
Newsletters may include highlights from RN or what’s new sections, along with additional content such as tips, user stories, announcements, coming-soon updates, promotions. They contain not only the product but also the company news.
This doc type serves as a way to engage with people, keep them informed, and encourage continued usage or participation.
Changelog
A changelog is a document or a file that lists all changes made to a product across different versions or releases. It is more technical in nature than the customer-facing docs described above. Basically, a changelog is written by the internal team and for the internal team.
A changelog provides a chronological record of changes, including bug fixes, feature enhancements, and other modifications that have been made to the software product over time. Usually, there is 1 changelog for the whole product life cycle.
Unlike release notes, which are more user-focused, changelogs are primarily intended for technical users, such as Developers, QAs, Project Managers, admins, and integrators — people who need to keep track of the product’s development history, progress, and issues.
Typically, Tech Writers do not create changelogs. This is a task for the Project Manager or Developers. A changelog is often maintained as a text file, a spreadsheet, a database, or a version control system. It can also be generated automatically by a tool or script. A changelog does not have to be pretty (unlike release notes, what’s new, and newsletter).
Summing up
Release notes, what’s new, a newsletter, and a changelog are 4 different types of documentation. They all describe changes in a software product, but they have different purposes, formats, audiences, and distribution channels.
Here is a comparison table summarizing the differences.
Now, by understanding the difference between these doc types, it’s much easier to communicate the product changes more effectively and efficiently. Also, now you know who should be responsible for creating each type of documentation.
And what about your project? Who creates the release notes and the changelog?
