I really enjoy reading changelogs, and wanted my own to be good too.
I love reading changelogs- especially for my fav tools.
Every time I see "Update and see what's new 👀" from Notion, I get excited.
After reading Hiten Shah's newsletter on changelogs back in Feb, I always knew I wanted to keep a good changelog.
Why?
Because changelogs are impt for excitement and adoption of new features. It also shows you give a damn.
Unfortunately, some companies write vague or confusing changelogs
v.1.2.32 - Added Database Optimization
This was an actual changelog entry from a giant multi-million dollar company.
Whaaa? This could be referring to anything...
A good changelog should explain what the update is and the positive outcome for the user.
My goal is for our users to get excited every time they see an update from us and want to read and find out what's new. Exactly how I feel when I see the notification from Notion.
Importantly, the changelog should be easy to skim. I don't want to waste people's time.
Here's what ours looks like right now...(link)
Here are more thoughts on how I write them...
Broadly speaking, there are 3 types of updates:
- New features
- Improvements
- Bug fixes
So, why not label and group each change using these categories? Already that helps with clarity. Why don't more ppl do this?
Here's how I think of each type of update...
If it's a new feature: ⭐
- Label it
- Explain what the new feature does
- And where to find it (this helps with adoption)
For example:
New feature: You can now add header images to your newsletter. Use featured image or select a default image in settings.
If it's an improvement: 🔨
- Label it
- Explain what it is
- And the benefit to the user
For example:
Improvement: Scheduling a post for publishing now works for newsletters too. Lets you write your newsletter now and schedule it to send later.
If it's a bug: 🐛
- Label it
- Explain the problem and how its fixed.
- Bonus points if you use your customer's words to explain the bug. This will help them understand what's fixed. Overly technical but abstract explanations don't help anyone.
For example:
Bug fix: Segments now show up properly when switching between audiences for Mailchimp connection.
Bundle the random small stuff:
Often there are a bunch of boring optimisations and bug fixes that don't need to have their own line. Bundling and publishing them anyway shows you sweat the little stuff, without boring people to death. Obviously what constitutes the little stuff is dependent upon your software and market.
- Label it
- State positive outcome clearly but briefly
For example:
Other small improvements: Simplified UI and copy across plugin
The result is something like this...
New feature: You can now add header images to your newsletter. Use featured image or select a default image in settings.
Bug fix: Fixed email responsiveness causing images to get squished in emails
Improvement: Scheduling a post for publishing now works for newsletters too
Other small improvements: Simplified UI and copy across plugin
There's obviously lots that can be improved on, but I think it's much clearer than many other changelogs.
Ultimately, like I mentioned at the top, I hope people will be able to quickly see what new features are in store for them, get excited, and keep using our product because they trust that we're care about it.
If you have opinions on this or suggestions on how I can improve, please let me know!
I'm always learning...
