Writing good changelogs seems to be one of those things that many of us talk about doing talk about wanting to see, but often don’t do it.

Or maybe it’s better to say that we often complain about the types of changelogs that we see, but don’t offer any advice of updates them ourselves.

And maybe that’s not the right thing to say. I mean, we do offer advice on how to update them. But does that stop us from writing better changelogs ourselves?

Writing Good Changelogs

The problem with writing good changelogs comes in two forms:

  1. They don’t do a good job of explaining the changes to the user,
  2. The “changelog” term is already jargon from the development community.

In our industry, one of our primary goals should be to make things as easy for the user as possible. Einstein is attributed with this quote (though there’s a chance it’s been misattributed) that reads:

Everything should be made as simple as possible, but no simpler.

It’s one of those phrases that become used so much that we begin to say them without regard to what’s it’s saying.

Is it silly to treat something as minuté as changelogs with this amount of care? To some, maybe. But I think if you care about the end-to-end of experience of your product regardless of how small it may be, then it shouldn’t be ignored.

1. A Better Explanation

If you’ve got a computer, tablet, or phone then you’ve no doubt seen an update message that reads something like this:

  • “Bug fixes and performance improvements”

Okay, that’s fine, I guess. But how generic can you get? If no software is perfect, then it’s always going to have bugs. And if a new version is released, then isn’t it expected some bugs will be fixed?

No, not this type of bug.

No, not this type of bug.

And if bugs exist, is it possible that those same bugs could be impacting performance? Sure, so then by fixing bugs, are performance improvements inherently being made?

Granted, these don’t always go hand-in-hand, but sometimes they do. Regardless, just stating this with each release doesn’t help anyone.

  • Specifically, what changes have been made?
  • What can I expect when I use this app the next time it starts?

Changelogs should answer a question.

2. Jargon from Our Community

There’s already an opportunity for us to be writing good changelogs (or better changelogs), but the word “changelog” in and of itself is a bit of jargon from our community already.

It’s not a term that you hear outside of technology (when’s the last time you got a changelog for the menu at your favorite restaurant?), so our users already have to use context to figure out what it even means.

I mean we could call it “Changes” or we could call it “Update Notes” or we could answer “What’s New?” But that’s not likely to happen so we have to do the best we can with what we have.

This means we need to be as clear as we can when writing out notes for our updates.

I’m Guilty of This

I started thinking about this specifically when I was working on the notes for an update that was recently released.

Writing Better Changelogs

Specifically, the updates said:

  • Add PHPUnit via Composer
  • Update .gitignore for the /vendor/, .DS_Store, and test scaffold files
  • Update Easer_Excerpts->init() to return false for clarity
  • Add unit tests

And that’s a terrible set of notes for users. I’m not saying that this shouldn’t be included in the notes, but it shouldn’t be at the top. Instead, why not state something like:

  • Improving the quality of the software by providing a set of tests that verify the project works as it should.

From there, there’s still room for improvement, but it’s much better than such a boring set of bullet points that are listed above. And this doesn’t mean those points can’t be mentioned. It just means that it shouldn’t be listed first.

Anyway, writing better changelogs is something we should do however it may look within the context of our work. And it’s something I plan to do with the next thing I release.