We Need to Be Writing Good Changelogs

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 becomes 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’s 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.

16 Replies to “We Need to Be Writing Good Changelogs”

  1. I love writing changelogs! It’s my favorite part of the release process. I’m serious. It’s fantastic to sum up everything we’ve been doing and why the user should be excited about it. We’ve even been known to convert them into blog posts.

    I agree that the word itself kind of stinks. It’d be so much better to simply rename it what’s new.

    Good for you committing. I’ll keep an eye out.

    1. We’ve even been known to convert them into blog posts.

      That’s something that I, as a user, often really appreciate as well. It gets me excited about the update when I can see all the hard work that went in to the update and all the new bells and whistles that are being implemented.

      I think it’s especially effective when those kinds of changelog/blog posts are posted to social media as well, because you never know who is listening. Sometimes, changelog/blog posts even convert me into a user of a plugin/theme/app/service when I never was one before.

    2. It’s fantastic to sum up everything we’ve been doing and why the user should be excited about it. We’ve even been known to convert them into blog posts.

      I think this is a good idea because not every reads changelogs. In fact, I’d guess that more users read blog posts than they do changelogs because they are traditionally more accessible (since changelog sounds like a nerd word anyway :).

  2. This post couldn’t have come at a better time! I am at the beginning stages of a large WordPress project and maintaining the changelog for a project of this size is something I have been struggling with.

    I feel as though there is a fine line somewhere in there, I want the changelog to be informative and easily understandable by the end user, however, I’m not trying to right a NY Times best-seller either.

    What would be super helpful is if you could provide us with a couple examples of what you might consider to be the “perfect/ideal/most fantasmagastik” changelog. ;-)

    1. This post couldn’t have come at a better time! I am at the beginning stages of a large WordPress project and maintaining the changelog for a project of this size is something I have been struggling with.

      Awesome – I’m glad it helps! I’ll also share a few more resources that I’ve found useful (and that others in the development community have shared with me):

      I feel as though there is a fine line somewhere in there, I want the changelog to be informative and easily understandable by the end user, however, I’m not trying to right a NY Times best-seller either.

      Exactly! Take some time to read through the first URL shared above and I think you’ll find it useful. It’s still something I’m working to balance, as well.

      What would be super helpful is if you could provide us with a couple examples of what you might consider to be the “perfect/ideal/most fantasmagastik” changelog. ;-)

      If I could, I would ;P but I’m still working on making sure my own changelogs are as nice as I’d like them. I’ve shared some of mine that I don’t like as an example. Once I continue to refine my own, I’ll be sure to share those, too :).

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

    While a changelog for the user may be helpful, but IMO changelogs are made for the developers and there’s nothing wrong with that.

    If there were a huge update where a user must know, a traditional blog post / email / front end notification (like WordPress big updates) would still be the best solution.

    I think changelogs are supposed to be short, sweet and as informative as possible. It might help a lot to have a category (BUG:, ADDED:, UPDATED:, etc) at the beginning and arrange the list according to the categories.

    As for better writing changelogs in general, I often ask myself, “If I were to look back at this half a year later, would I still understand what I wrote?”

    With that said, I couldn’t agree more with you that ““Bug fixes and performance improvements” should be elaborated further.

    1. While a changelog for the user may be helpful, but IMO changelogs are made for the developers and there’s nothing wrong with that.

      I want to say that I both agree and disagree with your comment but that doesn’t even make sense ;) so I’ll do my best to clarify: I agree that they are helpful for developers and that they are for them, at least they were for them once upon a time. Now, though, users have access to them via sites on GitHub and other public repositories so we know non-technical people do have more access to them than before.

      Because of that and because they are often put in the face of end users, it’s important to make sure that we’re doing what we can to pay attention to both users and developers.

      I hope that’s clear :).

      If there were a huge update where a user must know, a traditional blog post / email / front end notification (like WordPress big updates) would still be the best solution.

      Agreed! But if we have the ability to communicate via email, via blogs, and via changelogs, why not hit all the high points? At the very least, make a link to the blog post at the top of the changelog and then say something along the lines that the rest of the content is more technical or something like that.

      Admittedly, I’m still figuring this out, too.

      As for better writing changelogs in general, I often ask myself, “If I were to look back at this half a year later, would I still understand what I wrote?”

      I agree with this completely. +1.

      1. Hey Tom,

        non-technical people do have more access to them than before.

        That is undeniably true. And I’m on the fence with this one. If users do have the intend to dig places such as Github for information, wouldn’t they desire to understand our language?

        make a link to the blog post at the top of the changelog

        That is actually a very good idea! Note taken. Thanks!

        1. wouldn’t they desire to understand our language?

          I don’t necessarily think so. I don’t think it’s any more true of when we go to a mechanic to have something fixed with our car or when we call an electrician to fix a complicated problem in the house. Granted, these are just examples but I think they make my point.

          As long as I know what’s fixed and know what the problem was at a high-level and what to expect, I’m generally happy.

          That is actually a very good idea! Note taken. Thanks!

          No problem!

  4. Hi Tom,

    Changelog is for those who wonder if they need to upgrade a.s.a.p or it can wait.

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

    This phrase means to me: “Tom was doing something internal. I do not care. Will upgrade next week”. Practically same as “Oh, I just learned Composer and PHPUnit!!!!”

    If you’d say “Support WP 4.5” – and I know that WP release is tomorrow – that’s a good call for action.

    (or “Fixed an ugly fatal error when button is clicked 5 times in a row”)

    :)

    1. Changelog is for those who wonder if they need to upgrade a.s.a.p or it can wait.

      I think this is more or less what it used to before, but it now it kind of plays double-duty in that it does this and it informs users of what to expect when they do upgrade.

      This phrase means to me: “Tom was doing something internal. I do not care. Will upgrade next week”. Practically same as “Oh, I just learned Composer and PHPUnit!!!!”

      Ah, I never meant for it to strike anyone as “I just learned Composer and PHPUnit” as I’ve been using those in prior projects. It’s just that I wanted to begin incorporating them in plugins now, early on, rather than later.

      Nonetheless, I understand your point but it still demonstrates as to why we need to do a better job of writing clear, concise, notes for humans rather than just regurgitating what a GitHub commit might be :).

      If you’d say “Support WP 4.5” – and I know that WP release is tomorrow – that’s a good call for action. (or “Fixed an ugly fatal error when button is clicked 5 times in a row”)

      Agreed! :)

    1. Wow. Your 3.0 release notes nicely walk the line between being user friendly but also handy for developers. The annotated links to the individual issues is a smart way to keep it simple but also offer the details. Nicely done.

    2. Even since writing this article, one thing I’ve started to do is to add a sentence or two above the bullet points that explains, in plain language, what to expect. After that, there’s a bullet list of the more technical changes that are usually based on the Git commits.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.