Software, Development, and WordPress

My Opinion on WordPress Change Logs

As far as WordPress-related news is concerned, I think that both Post Status and WP Tavern are two of the best places to get consistent reporting on a variety of topics that range anywhere from things for standard end-users through things with designers and developers.

I’m not really a fan of doing any type of commentary of coverage-of-coverage (so meta, right?), but WP Tavern recently ran an article that I’ve been thinking about since I read it.

Specifically, the article was titled: WordPress Plugin Developers Need to Communicate Better in Change Logs.

 WordPress Plugin Developers Need to Communicate Better in Change Logs

Though there aren’t many, I think reading each of the comments is something worth doing if you haven’t already done so.

Anyway, as far as the general topic of the article is concerned, I couldn’t agree more – both as an end-user and as a developer, and I wanted to share my own thoughts on the topic if for no other reason than to share my own perspective on the topic.

WordPress Change Logs

Traditionally, a change log is defined as the following:

A changelog is a log or record of all the changes made to a project, such as a website or software project, usually including such records as bug fixes, new features, etc. Some open source projects include a changelog as one of the top level files in their distribution.

I know, I know – this may read kinda boring – but bear with me.

Generally speaking, a change log (or Changelog or ChangeLog or CHANGELOG – does it even really matter?) is supposed to capture all of the changes that have been introduced into a software project since the last release.

But the challenges of doing this is that:

  • Change Logs are typically written in developer-speak (or jargon, for most people)
  • The name of the file – that is, specifically, Change Log is not a phrase that the average user will be using

Instead, shouldn’t we be including something that’s a little more user-friendly? That is, maybe we should be including something like “Changes” or “Here’s What’s Updated” or something a little easier to follow.

Furthermore, why not separate the technical changes from the changes that the users actually care about into a separate file. Perhaps these changes can be listed out in, say, 140 characters or something like that (I mention that just because we’re so used to tweets in our current culture).

From there, we could link to a longer blog post or something similar to help the users follow exactly what’s changed.

Don’t Get Rid Of Change Logs

Anyway, I’m not saying that we abandon Change Logs – I think they are necessary and we need them for all software projects especially those that are developed by teams (open source or not) – but maybe it’s time we start thinking about including something else that’s a little more user-friendly for those who are using our work.

Case in point:

When you download a software update or an app update for your phone, how annoying is it to read that the changes in the upcoming version of “Bugs squashed” or “Performance improvements.”

What does that even mean? From a technical perspective, I want to know more. What bugs were squashed, specifically? What did you do to really improve performance (or is it supposed to induce a placebo effect)?

These same types of things can permeate WordPress development, as well.

To that end, we can do a better job of communicating to our users and our customers the changes that we’re introducing into our work without boring them with technical details.

We’re generally capable of writing both technical documentation – for a classical Change Log – and documentation for our customers – for a type of “Changes” document, or something like that.

I know that there are some people who are super particular about the files that are packaged with their downloads – that is, they want the files of a certain format, of a certain naming convention, of a certain file format, but I think that if we let the technical formalities get in the way of taking care of our users, we’ve got our priorities mixed up.

Thanks To WP Tavern

So props to WP Tavern for bringing up this topic, and props to those who have chimed in via the comments.

I wanted to share my thoughts, but the more I write, the longer my opinion [clearly] got so it seemed better positioned as a blog post than as a comment.


  1. Jason Lemieux

    I like the idea of splitting it up into two files: what’s new, and a more traditional developer centric change log. Props to that.

    We keep our change log very user-friendly, and don’t tell developers much at all. We use it more as a what’s new. If there was a second, more developer-centric place to dump technical changes I would support it.

    • Tom

      Yeah, I’ve always been a fan of your change logs – they’re easy to understand, I know what functionality to expect, and I know how to use the plugin once it’s been upgraded.

      This doesn’t mean I’m not interested in a more technical overview, but when I’m going through my dashboard an upgrading things, I’m more concerned with the ‘okay so now this works’ versus the ‘how did they do [whatever the problem was].’

      • Jason Lemieux

        Thanks. Once in a while we’ll get lazy and slip in a misc bug fixes line when the issue which was fixed is too complicated to explain but otherwise we try to keep it friendly and helpful. Our development is so rapid sometimes that I often don’t realize everything we have done. Sitting down and combing through bitbucket issues, basecamp todos, and support emails to generate a definitive list is actually loads of fun. And, I hope, good for the team to see. It’s a nice place to pull it all together.

        • Tom

          One thing my team and I used to do when we were working on themes was to comb through the GitHub commits to generate the change log.

          Obviously, this is far more technical than anything I’m talking about here, it was years ago, and I wouldn’t necessarily say it’s a good idea in terms of what I’m talking about in this post, but it’s something that I still think should be bundled as a more technical document for those who are interested.

  2. Danny Brown

    Great points, Tom. As a heavy WordPress user, albeit a non-techy one, my head often spins when I read changelogs. I get they need to convey a message, but wouldn’t it be better to convey it for the average user, as opposed to the dev-minded one?

    • Tom

      Totally understand – there’s definitely a time and a place to cover the technical details, but I don’t the the change log that end users see is the place to include that information. I mean, do they really care how the problem was solved or improved or just that it was solved and/or improved?

      • Danny Brown (@DannyBrown)

        Exactly. They just want to know bugs are fixed, and what new features will make their lives easier. At least, that’s all I want to know. :)

  3. Jon Campbell

    If I am looking at the changelog for a plugin or theme I am usually searching to see if they fixed a particular bug or security flaw. Typically I find the security fixes get a more detailed mention but the bug fixes are not addressed itemized with details.

  4. Rick

    I am completely on the same page Tom,

    As a coder I actually tend however to not read whats changed in code unless its something I need be aware of. If Telerik makes changes I have to know. If a widget gadget makes changes I just read whats applicable towards use. Thats just me, I tend separate it where I can.

    In as far as what I do in a change log I dont even call it change log. I have a “Whats new” file for the user and if anything code wise needs be mentioned at all that is done in an Updates file. But, WP is a different ecosystem than what I have dealt with before.

    There has always been this rather funk surrounding software for as long as I can remember, even when we were creating video games that we’d drop off to local stores in sealed plastic bags in the TRS-80 Model 1 days.

    My father who passed 3 years ago used to get upset by it. He did not care about the jargon or details, hows and why’s and wherefore’s. Software ought work for the user without them needing know details. Help systems should be built into all software so a user does not need plod through searching or seeking, they should be context sensitive to what a user is doing at the moment as well. Updates should only show changes to the software that affect the user of the software or issue in new features. On and on… That was my Dad.

    Most of what he said and got rather heated about in respect to it all came true. Most applications software has extensive help systems. Most software has a context sensitive help capability. Most software when updates occur show the user what they need to know, nothing more, nothing less.

    Question is why should the online applications be different?

    Answer, many are not except in the PHP universe or Open architecture universe.

    This is another facet of “Windows Online” in scant years that will end up turning the web upside down. As a user of whatall, a CMS, which would you rather use? One with an extensive context reader help system or one that has you Google’n or Bing Bing Bingin’ to find information?

    For programmers, same deal. PHP applications in the Open Source community tend to use many different tools all from differing entities that cobble together, PHPDoc, before GIT, Mercurial, SVN, This IDE or that one (I use many at once), etc etc.

    I do not know if its all due to tools emerging as standards or more, “This works better” and people just flock to it. In .NET its pretty much, “Here it is, tried, true, done by hundreds of millions of developers and users… This is how its done”.

    Even as noted in developer documentation. Look at The Mono Project doc’s and look at pretty much any PHP app and most (not all) frameworks. The difference is significant. Which of these results in a more productive coder?

    From a users perspective I cant imagine many webmasters reading changelogs. The lions share of folks dont do it in video games or applications. Instead its automagically presented to them through often a help system or specific menu / dialog in many cases blasting them over to a webpage for the info and then said webpage often being used to upsell.

    Now whether anyone likes that stuff is rather immaterial as that is the future of Web App’s as well. The online OS’s are going to change everything.

    If I were a WP advisor I’d be suggesting:

    A comprehensive help system that is context sensitive. For theme’s, plugins & core.
    Change the backend UI out using customiser and make that UI either like Windows or Mac and allow that to be skinned.
    Include CPT, Taxonomy and Meta box creation as part of WP Core.
    Create the equivalent of Joomla Module positions. Custom content positions in a web theme that are “named” in the theme where the end user can assign a menu or category or taxonomy, image whatall. A sorta “anything can go here container” and setting the properties thereof. Sorta a more flexible widget area but built in and specific to core capabilities.

    • Tom

      I think you definitely bring up some interesting points as to how the change logs work across various software systems.

      I’d love to see the things for WordPress continue to get more user-friendly – and despite being a pessimistic – I actually think it could happen. It’ll just take time like any major change, really.

  5. Rick

    If I had the time I’d be all over it two fold. But I have to chase meat & potatoes. A context sensitive help system both front facing and the administration side. Versatile enough to suite developers needs of change logs as well. There are also other active facets in the front end user experience it could be used for in respect to rapid location of grouped content “automattic’ly” (giggle).

    A site with TONS of archive content, Codex, anyplace where rapid access to structured information is a need. Slap atop it the old “drilled intelligence” engine for the meek. That is to say, selectable choices that assist them in drilling down to content they seek.

    Sure, someone could create a plugin that does this. But there is no mandated usage thereof. So, some developers will, some wont. That ends up in the mish mosh user experience.

    Lastly… Think of what it would DO for handicapped people. As I said, I am working on a pro-Bono Multiple Sclerosis site. Alot of folks with MS use screen-readers or synthesized voice tools.

    If I want to be friendly I cant have 10 posts with “read more” as its “read more what?” to a screen reader or voice synthesis tool. I have to have, “Read More About How Demyelinization And Its Impact On Neural Communication”… Every article.

    Instead of a screen reader having access to context sensitive help applied to the Read More so the reader knows which link is which and not having to either clutter front facing web for people whos disability hasnt impacted sight. So, I mean to be brief (which I seem to have a handicap at LOL) think of the possibilities it adds to WP, Now perhaps the NY Times becomes not only more navigable in normal respects in finding specific information(s) but they also could be far more accessible to people with disabilities.

    Instead, all this is being left to developers or themes.

    If it were to happen the question becomes implementation thereof.

    Here’s what I would do.

    Inside the WordPress admin backend an application in JQuery that is ALOT like a windows application. Based upon active page elements and allowing the webmaster or developer to create the help system interactive. Then pulling it in with the page queries from DB so no extra trips are needed out to the DB and of course supporting language translation file(s).

    That DOESNT work for the NY times. For them, the BIG BIG sites. A Windows / Mac app that does the exact same thing but is a separated work flow. Developers could also use it.

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑