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.

Share:

Leave a Reply