Tell IH: Keep A Public Changelog
If you’re building in public, sharing your progress in a CHANGELOG.md and on Twitter is easy. But there are many reasons why you should also have a public customer-facing changelog. Here are some:
- It’s a great marketing tool: Potential and existing customers see that your product is under active development, building trust and confidence.
- It’s free SEO: If you, like me, struggle with creating content purely for the sake of SEO, this is a great way to get started. Relevant keywords will be part of your content organically.
- It’s motivating: Looking at a nicely designed changelog page can give you a great sense of accomplishment when you realize the progress you’ve made over time.
- It’s low-maintenance: Product update posts don’t need to be updated after you’ve published them.
If you are curious what such a changelog page could look like, here’s the one I’ve just built for my Open Source email newsletter tool Keila:
https://keila.io/updates
In case you’re wondering how I build this page: I’ve published the entire code of the Keila website on GitHub. This is the commit adding the changelog:
https://github.com/pentacent/keila-web/commit/97f4439affcd6a659f83fbf1d454e55f66fefdef
Credit where credit is due: This is the page that originally inspired me to build a customer-facing changelog: https://refiner.io/docs/kb/getting-started/product-updates/
Thanks to @mdausinger for sharing the idea on Twitter:
I really like this, a lot.
However, most of the changes we do for https://www.daito.io are not user-facing. Should only list user-facing changes? Any tips on where to draw the line?
I started with the public changelog at version 0.9 of Keila. The full changelog is here: https://github.com/pentacent/keila/blob/main/CHANGELOG.md
As you can see, I decided to group some things together (even though they are separate entries in the technical Changelog). I also omitted the changes that are not relevant to users, such as updating dependencies or adding support for DevContainers.
So to answer your question: I would only include changes that users can notice somehow. But if you’ve done a big refactoring that improves performance for users, I would include that as well.
How do you handle versioning? We sometimes do multiple deploys a day, sometimes a week goes by without a deploy. Seems like regular semantic versioning would not be a great fit for a fully agile pipeline. Any ideas?
Also, do you track who is checking the changelog? Do you have any metrics/idea of the impact this has on e.g. user acquisition?
I decided that for the public-facing changelog, there’s no need for version numbers; instead I simply use dates. I do use semantic versioning for Keila, but those versions aren’t necessarily relevant for SaaS users.
And since I’ve only just launched the changelog, there’s no data yet.