When you are a small team, bringing your ideas to life – you will have emphatic focus on the development part. And more often than not, documentation will be an afterthought. That, is the nature of most software development teams.
But as your software product gets off the ground, you feel the need to be a bit more organised. Otherwise it will become near impossible to collaborate with your growing team.
That is when the customer feedback starts to flow in. Your colleagues from marketing & sales team are relaying the objections they heard. Your product roadmap is now taking up a nice shape. You start to iterate and build on what matters & peel off that doesn’t.
But when you look back, it is too difficult to see where you are coming from. Because the evolution of your software is not documented anywhere.
This is where changelogs (or change logs) come in. They act as a bridge between the current version of your software product & its past. When written effectively, this powerful tool can build credibility and confidence among your team members as well as customers. The importance of changelogs can be seen in open source solution that are developed by a group of developers all over the world.
Here is a brief article on how to write an effective changelog for your software product, be it open source or proprietary, along with some considerations and warnings.
Why do we use a changelog & What is its purpose?
Perhaps you’ve heard of the term “changelog” but aren’t quite sure what it is. Simply put, changelog is a documented record of all the changes that a software undergoes. Changes made are then chronologically recorded for users to easily spot the evolution of the product. Following a defined changelog format can help in tracking the changes made in a systematic way, and help contributors to identify notable changes easily.
Changelogs Vs Release Notes
Without a proper changelog example to refer to, users might confuse them with release notes. But they aren’t quite the same thing.
Release notes are documents giving a wordy description about the release of a new version for a service or product. They usually contain detailed information about the changes made as well as their impact on the end users. They also include the bugs resolved, and in case of open source software – release notes can even serve as a user manual.
But, changelogs are terse & to the point. They are lists of additions, removals & changes to the software. They mean more for the team that develops the software than the customers. At times, they will also contain some technical details that are not relevant for the end users – like bug fix details.
In other words, release notes use more comprehensive language for explaining what has changed or hasn’t changed – and changelogs list notable changes made in a less verbose way & are more technical oriented: they can be generated with the help of a changelog tool, like release notes.
Where do you put changelog?
Changelogs can have different styles and locations, but they’re a must on every project. They can be presented as blog posts, as a *.md file in a GitHub repository, in the changelog section of the software (or its website), in “What’s new” on the Android play and Apple app stores… As long as there is a clearly defined space for changelogs to exist (and that space is clearly known and easily accessible by stakeholders), it should be good.
How do you maintain a changelog?
Here are 4 tips to help you write an effective changelog.
1.Use Reverse Chronology
This is the most important one. Be sure that the latest versions are placed first. Consider that rarely your audience will be interested in looking at what happened years ago. It is always the latest changes that interest most of us.
Doing this will not only help your readers but also market the fact that you are constantly improving the product. That there is a steady paced development team supporting the software.
Here is a snapshot from Confluence cloud changelog.
2.Do Proper Formatting
Avoid long sentences and paragraphs. Keep your audience engaged by visual formatting.
This entails using headings, subheadings and bullets. This will make your changelog reader-friendly. Consider writing it down in markdown or markup. Carefully weave the content using italics, bold text and code fences if they’re required.
Breaking down the changelog into multiple visual parts is even more critical for projects with several components.
3.Grab Their Attention Early
Consider that most people are in a hurry these days, besides having a very short attention span.
Thus, highlight different types of changes with various visuals. Many teams rely on colored lozenges to achieve this. Different colors can be used to a different component, feature, types of changes or even pricing plans the changes impact. It could be anything, as long as it makes sense for your audience.
4.Provide Additional Details
While the changelogs are not verbose, they shouldn’t prevent a curious reader from knowing more.
Always provide links to detailed blog posts, videos etc. It is not uncommon to see a link ‘Know more’ at the bottom of an item in the changelog. Heck, even pointing the users to comprehensive release notes should be ok. As long as there is a history that can detail out the progression, it should work.
Some teams publish names of the developers who contributed to this change – Github has enough examples that feature names of those who have worked on various functions of open source software. Again, use the space creatively & make your changelog colorful.
What is a good changelog?
Creating good changelogs is not difficult, but it isn’t easy either. Here are a few pointers that can help in making a changelog better:
- Always include a complete history of notable changes. This lets your changelog serve as a historical reference. Don’t make the mistake of assuming the changelog is just being used for the latest updates.
- Include the “when” for each of the updates. This is helpful if a bug should be found several months following an update being installed.
- Be sure to note anything that was changed, added, removed, fixed or deprecated as well as any breaking changes.
- Never assume anything, such as users knowing about the name of a module.
- Add sufficient white space so that your changelog doesn’t look busy.
- Include a summary—This makes your changelog much easier to understand and takes minimal effort.
- Group changes of the same type together while setting the changelog format. This makes the changelog more readable and organized.
- Use one-word categories for describing the kind of changes made.
- Don’t forget to update deprecations—You need to inform your users if your project’s latest version includes breaking changes. Also, be sure to list any removals.
- Don’t use a commit log diff as a changelog.
