If you thought changelogs were just document what has changed – you’re wrong.
That may be what you do in a changelog, but what’s often not seen is how they act as bridge between the software developer and users.
It’s a shame because this is incredibly powerful – with this you can:
- demonstrate good communication, attention to detail and professionalism to the users
- show a continued development cycle – which builds confidence
- refer users to related documentation.
Instead they’re often underrated – and hence poorly done. I’ve seen some shocking examples – ranging from vague, over-detailed or even worse – just a link to a “diff” that shows what code has changed.
Here I’m going to share some tips on how to write a change log that matters to the user. More information on what makes a good change log can be found at Keep a Changelog.
Know your audience
As with any writing – the first step is to know your audience.
Are your users all technically minded, for example if you had a developer tool, or are they the type of user that is only capable of installing a WordPress plugin?
I usually consider my audience as:
- my mother
- a developer
- myself
The key here is you need to write to the lowest level – so I always think “does this pass the mother test” — “will she understand what this means”.
Keep It Simple Stupid
Avoid using technical terms in the changelog and only talk in general terms.
For example
BAD: added async processing of ZIP file
BETTER: improve time taken to create ZIP file
The level of detail to include will likely be contextual, for example – do you need to refer to where ZIP files are created? If so,
BETTER: improve time to send notification email with ZIP file
Write in terms of features
Most users are interested in the what – not the how. It can be hard to remember this when you spend so long thinking about how things work and making it happen.
For example
BAD: minify JS and CSS
BETTER: make page load quicker by reducing size of JavaSript and CSS
Avoid technical documentation
Don’t fall into the trap of including technical documentation in a changelog – for example providing examples on how actions or filters can be used.
Unlike a changelog, technical documentation is not set in stone – it’s a living breathing beast. What happens when that filter gets a new parameter – will you be retrospectively changing the past changelog entries? (I hope not!)
Instead simply provide a high level reference to the technical element, for example the name of a new or updated filter – and provide a link to the official documentation.
If this isn’t an option at least provide inline documentation in the code.
Break it down
If your changelog is for a complicated multi-part project, for example software that has a front-end and an API – use headings to break updates into their relevant part.
For example
Front-end + make page load quicker by reducing size of JavaSript and CSS API + improve time to send notification email with ZIP file
Categorise
Before each item in the changelog, prefix with a category that describes the type of change in a single word.
For example
- Feature – for new features
- Improved – for general improvements
- Maintenance – for tidying code
- Changed – for changes in existing functionality
- Deprecated – for soon-to-be removed features
- Removed – for removed features
- Fixed – for any bug fixes
- Security – in case of vulnerabilities
Decide on how you want to do this early on and continue to use it as a “controlled vocabulary” – your users will rely on this being consistently used so they can scan through the list.
Don’t forget WHEN
For each update, include at the top the version number and the date the update was released.
This can help when jumping multiple versions or if a bug is discovered several months after the update is installed.
Include the full history
Don’t assume that the changelog is only being used for the latest updates.
By including the full history you allow the changelog to be used as a historical reference – for your users and the developer.
Anything else?
What else do you think makes a changelog matter for the user – comment below.