Creating a changelog, or displaying public release notes on your landing page can help you connect with your customers, build customer trust and show your users that you’re constantly improving your product and finding new solutions to their problems.

But it’s not enough to take a changelog from Github and throw it up on your site.

When you’re writing a public changelog or a product “What’s New” style page, it’s really important to consider your audience. A public changelog is no longer just a tool for other programmers and members of your team, so the way you write it needs to fundamentally change.

Here are three of the most common mistakes that we see companies making when working with a changelog app like ChangeCrab, and how you can avoid them.

1. Getting too technical

The original concept of a changelog is rooted in the development and technical professions, so many web developers and entrepreneurs with a software background tend to approach all changelogs with a 'programming' rather than a 'marketing' mindset.

Consider your audience - even though many online and SaaS businesses do appeal to tech-savvy users, it’s often the marketing members in those teams that are going to be the ones who purchase or use your product. You need to write in a way that appeals to those users.

This doesn’t mean every release note needs to be a sales pitch — but it does mean you should think about when and how it’s best to explain the solution to a problem from a technical perspective and just how deep you want to go with those posts. The exact balance you strike will depend on your branding, but try to remember that even programmers (!) prefer to read something that maintains their interest.

2. Vague-noting

On the flipside of extremely dry, technical notes, you have vague-noting. It's the dreaded “fixed bugs” or “updated user experience” comments that you've seen before. Mobile phone updates are also often famous for this, and it's also common on updates from larger companies who don't want to go into detail about problems and bugs.

What does “fixed bugs” really tell a reader? Nothing! So these vague-notes are wasting both your time and your users time. Remember, the people reading your release notes are always going to be your most excited, most engaged audience and they DO want to hear about the changes you made, so don’t be afraid to speak about them.

And if you really think a change you’ve made isn’t worthy of an update, well, then pat yourself on the back instead and don't post at all. Simply not making an update is better than vague-noting, as consistently posting pointless updates are going to drive any potential readers away.

3. Clumping

What, you might ask, is clumping?

Clumping is when a product goes through a bunch of changes that don’t get documented when they’re released, and then after a long time passes, there's a single release note or changelog entry for ten different features and a hundred bug fixes.

This is a common occurrence on sites that don’t use dedicated changelog software like ChangeCrab. Normal, non-dedicated methods for talking about product updates trend toward blogs and emails. Both are excellent communication tools, but large blogging and email platforms simply aren’t very well suited to short, frequent posting.

This has two negative side-effects. Firstly, it makes your updates seem less organic and more rushed. Secondly, the longer a release note post is, the less likely your customers are to actually read it all in the first place.

However, this logic doesn’t need to apply when you use a changelog app. Because ChangeCrab, let’s you post in seconds and display those changes anywhere on your site, you can post more frequently with smaller, punchier changes. This also means if you fix a critical bug or problem then more of your users are likely to see that you’re on top of the problem as it happens.

And as an added benefit of ChangeCrab, if your most engaged users do want to get emails about each of your changes, they can do that, too! You can optionally set-up changelog e-mail alerts for those customers and get the best of both worlds.