The tone of your changelog can deviate dramatically depending on what your intended outcome from providing changelogs is. In a world of nuances it might be helpful to boil an otherwise complex question into its simplest form: Are you writing as a marketing exercise or a support one?

Of course there is overlap between both styles. You’d have to try pretty hard to write a changelog that doesn’t offer some level of support, and equally writing about changes and it not involving some level of marketing would be an impressive feat. With all that said once you’ve decided your root intent you can build out your changelog and having some idea of your style can help keep your changelog clear and consistent.

Marketing Driven Changelogs

These are changelogs which have the primary intent of ensuring your users know you are keeping the software up to date, while also offering a glimpse into the inner workings of your company. They humanise an otherwise sterile process of pushing out improvements and fixes.

When you’re writing for marketing you can be much more liberal with your word count and flair, as ultimately without a little personality your notes become a matter of fact and offer little else than telling your users what has changed.

It can be a lot more nerve wracking when writing to entertain as well as inform and perhaps this is one of the defining reasons so many decide to produce a list of changes rather than add any personality to the post. If we think all the way back to 2015 - remember being able to visit pubs? - Tumblr released a big patch with what would certainly be described as being ‘creative’. The patch notes provided the core details of what was being changed but in the form of technology fanfiction.

There is no avoiding at the time it was something of a controversial decision, and 6 years later people will still very much be on both sides of the fence when it comes to patch notes and how succinct they should be. Was it worth it for Tumblr though? Well ask yourself when was the last time you remember leading national newspapers writing about positive changes in a software application? Yeah, I’d say it worked.

So am I saying you need to go as extreme as Tumblr? No. You’re less likely to ride a wave of national press each update you do, even if you are the next up and coming Tolkien. Tumblr managed to do creative patch notes because it’s a company that was trying to present itself as human and creative, open and inviting.

With more and more products competing in increasingly over-saturated markets, that personal touch that comes with more informal and human change logs can do wonders for a brand. It can remind people that behind that code there are people working, and people making choices they hope to benefit them, the customer.

Here are a few easy ways to make your changelog more human, more laid back and above all, more entertaining to actually read.

• Explain who worked on any given change if you’re a small team
• Put a few lines about the challenges you faced when rolling out this update
• If it was a suggestion from a user then expressly say so! Maybe even thank that user directly.
• Don’t jump right into the changelog ‘facts’ - give a few lines about how you got to this update
• Avoid doing massive lists of changes at once and instead post smaller, more frequent updates
• Never forget that outside of any creative writing you may want to introduce to your change logs, they should still very much make it clear what has actually changed. Just want to do some creative writing? Your company blog is probably a better destination. It’s all about balance!

Support Driven Changelogs.

Alright - decided you want to go the support driven route with your change logs? That’s great because you’ve just made your life a lot easier. Perhaps if you’ve decided to go the marketing driven approach as above it might be best to stop reading now as support driven logs can appeal purely as they require a lot less effort on your part.

With a support driven change log the most important detail is to get over the critical changes and the changes that impact users as quickly as possible. However, it’s important to remember even a support focused changelog is different from a traditional, more internal changelog that you may have written as a developer.

In a traditional changelog we’d likely be separating the changelog into fixed, updated, etc and have quite a clinical and precise way of organising everything. However, when we’re dealing with customers rather than other developers it may be prudent to separate them into major and minor changes.

Provide a simple list of the changes that will impact users in the major changes. These are changes such as large scale rollouts of new features, the removal of features and the other things that will materially impact how users will use your software. It’s always, it’s better to post these changes as the features are rolled-out rather than waiting and posting them all at once. Not only do smaller, more frequent updates demonstrate how active your company is, they’re also simply easier to read.

You should still post the minor changes as we discussed in the previous blogpost - it’s critical to let users know you are making changes even if those changes aren’t as easy to see right away. Doing so ensures that you seem active even when working on backend code that otherwise would be invisible.

Using a support driven changelog doesn’t mean you can’t use any of your - no doubt -charming personality however. Even practical bullet pointed changelogs can be introduced with a few lines of why you’ve made these changes.

Remember you are talking to customers not an internal development team so you may want to ensure you don’t just copy your latest commit messages. Simplify changes down to their benefit and impact, so as an example don’t tell people you’ve changed CSS frameworks from bootstrap to tailwind but rather something like “Migrated to Tailwind CSS to improve mobile responsiveness”

Finding the right voice for your business

I’ve set out above two ways you could approach your changelog, and although it may seem like I’m saying you have to pick one option or another in reality we deal more in detail and mixing of the two.. You may find the best outcome for you is to have a mixture of both - trying to saddle the path between fun and informative is a challenge but one that often can provide the most rewards.

As always, the best changelog isn’t one way or the other, but the one that fits in with your own brand personality and let’s the talent and communication of your team shine through.

As always, until next time - tata!

Daniel.