How to Keep SaaS Changelogs: Do’s and Dont’s
Knowing how to keep a changelog that is well-organized, easy to understand, and interesting to read will help keep users excited about your product changes and improve adoption.
Whether you’re a seasoned product manager, product marketer or just starting, this guide will give you the tips and tricks you need to create an effective changelog.
Why Keep a Changelog?
A changelog is like a logbook for your SaaS. It’s a place to keep track of all the changes you have made, such as new features, bug fixes, and other updates. Think of it as a way to keep everyone up-to-date and in the loop about what’s going on with your product.
However, the use of changelogs has evolved in recent years. Changelogs no longer serve only your internal team of developers and product managers. Due to the rising trend of PLG, users have become increasingly interested in changes affecting the products they love. As a result, changelogs now serve both an internal and external audience.
Who Needs a Changelog?
A changelog is essential for different stakeholders within your company, including sales, customer success, marketing, and product management. But in this article, we’re looking at public-facing changelogs i.e. a changelog meant for your users.
Customers use changelogs to stay informed about the latest software changes and to understand what new features, improvements, and use cases are available.
Structure of a Changelog Post
These are the key things you should include when you create a changelog.
- Date of change
- Description of change
- Category of change e.g. bug fix, new feature, improvement
- Impact on users: Explain how each change creates value for users. Highlight any new use cases that are now supported.
- Relevant links: Provide links to resources like videos or in-depth tutorials for additional context.
Check out these release notes templates to help you write effective release notes faster.
What Kind of Changes Should You Share in Your Changelog?
Generally, the following types of changes are included in a changelog:
- New features and functionalities
- Bug fixes
- Performance improvements
- Changes to the user interface
- Discontinued features or functionality that is no longer supported
- Security fixes and updates
Things can get messy and muddled when you’re improving things every day so it’s essential to keep the changelog organized and up-to-date with a clear and concise description of each change. That way, users and customers can understand what has been improved or changed in each update and they can make the most of what you’ve been working on.
How to Keep a Changelog
#1 Establish a consistent schedule for updating your changelog
This could be daily, weekly, or monthly, but choose a schedule that works for your team and stick to it. If you have a routine, you’re less likely to fall behind and get stuck doing a massive update.
#2 Use simple templates for your release notes
Templates can keep things standardized and speed-up the process of updating the changelog. Include a section for the date, a brief description of the change, and the value or benefit to your user. Check out this article for ready-to-copy templates for different kinds of release notes.
#3 Focus on the most relevant changes and updates
Instead of trying to include every single detail, ensure the information you include is relevant and valuable to your users. You can always provide a link to a more detailed video tutorial for interested users.
#4 Make it pop
Use bold text, italics, or different colors to highlight significant changes that users need to know about. Add visual elements like videos, images, and gifs to make your release notes pop.
#5 Keep it clear and simple
Use simple language, bullet points, and headings to make the changelog a breeze to read and understand.
#6 Make it accessible
The changelog should be easy to find and access – you don’t want your users to have to go hunting. The best way to do this is with a standalone changelog site and an in-app changelog widget, which presents your feature updates to your users right in your SaaS app.
#7 Ask for feedback
Ask users for feedback on what they think about the new updates. Maybe they expected something more. Or perhaps they have some questions. Collect this feedback and use it to improve your product and address users’ concerns.
#8 Tell them what to do next
Always add a clear CTA for users to take the next course of action. Some CTAs to consider are “Get started”, “Try now”, and “Sign in now”. CTAs help improve product adoption.
5 Don’ts While Keeping a Changelog
Here are 5 things you’ll want to avoid while keeping a changelog:
- Don’t make it invisible
The changelog should be accessible and easy to find; otherwise, users may not be aware of important feature announcements. Use multiple channels to put your feature announcements in front of your users. You can use email, in-app changelog widgets, or social media.
- Don’t make it too technical
It should be easy to read and understand for all your users, no matter how technically-minded, so avoid using complex language or jargon.
- Don’t skimp on details
You don’t want to ramble on forever but including only vague or incomplete information about changes can make the release note less helpful to users and customers.
- Don’t bury the important stuff
If you’re making a lot of changes, the most important ones can get lost in a sea of other updates. Make sure they’re easy to spot. People have a short attention span, so try to put your most important updates, like new features, in bold and at the top.
- Don’t make it a one-way interaction
The more interactive your changelog, the more your users will engage. A changelog can be a critical part of your product marketing strategy for interacting with your users. Video tutorials, feedback forms, and CTAs that lead users to try a feature are all good examples of interactivity.
Frequently Asked Questions
Can changelogs be bad?
Yes, changelogs can be “harmful” if they are not appropriately maintained. One of the major issues is ignoring deprecations. Things don’t go smoothly all the time, and some updates may not work well. Whenever there are such deprecations, make it clear in the changelog.
When there’s a lack of transparency, it leads to a lack of trust, which can hurt the product’s growth.
Is there a standard changelog format?
Not really. It depends on you. There’s the GNU changelog style guide which is entirely inadequate. You can, however, copy and paste the templates we provided in this article here as a starting point to write your release notes.
What should the changelog file be named?
You can call it CHANGELOG or WHAT’S NEW?, or RELEASES. Just think of a name that makes it easier for your non-technical users to identify and remember.
Should you ever rewrite a changelog?
Improving a changelog is always a good idea. Sometimes you may have missed mentioning a crucial change in the release notes for a specific version. It’s good practice to keep your changelog up to date in such cases.
How do I maintain a changelog with minimal effort?
The best way is to use templates to help write release notes faster, and a proper changelog tool like ReleaseLog that has a simple drag-and-drop editor to make it easy to write your notes.
Final Thoughts
In summary, a changelog is important in communicating changes about your product to users.
Create a schedule to keep your changelog accurate and up-to-date. This will help you spot any errors or omissions to ensure that it remains a valuable resource for everyone.
If you want to get started with a simple changelog, we recommend ReleaseLog by EarlyNode. It’s designed for busy SaaS founders and product managers who want a fast and simple way to keep users engaged and updated on product changes.
