What Lawn Care Taught Me About Why You Should Read Changelogs

You might want to communicate better with the yard care pro.  Creative Commons Image Attribution
You might want to communicate better with the yard care pro.
Creative Commons Image Attribution
My neighbors pay someone to cut their grass. As far as I can tell from being an only-mildly-nosy neighbor, here’s how the weekly-ish transaction goes:

Yard guy (we’ll call him Pete) shows up to mow the whole lawn. Right before he starts, Pete walks up to a cushioned chair on the front porch, and picks up his check from under the cushion.

Every now and again—but by no means on each transaction—there is a brief interaction between Pete and the lady of the house, who works from home. We’ll call her Julie.

Here’s where I am going to stretch an analogy to make my point: imagine that the only correspondence between Julie and Pete happens under that cushion, and is always initiated by Pete. In our hypothetical world, there’s no other way for Julie to communicate with Pete.

Now, further imagine that Julie has made some changes to her lawn and needs to communicate with Pete. How important does that envelope become?

You have just underscored the use of changelogs for WordPress developers.

The changelog is the only shot I have at communicating things to my users. If I make a change that affects everyone running a certain version of PHP, for example, there’s no way other than the changelogs to get that message out to folks.

I’m not overdramatizing things here: there is no mechanism for contacting users of my plugins.

There is no (other) mechanism for WordPress plugin devs to communicate with users. Read changelogs. Click To TweetMy best case scenario is that when a user installs my plugin they opt in to my newsletters on the settings page of that plugin. But with over 10,000 plugin active users on one plugin and 7,000 active users on another, I can assure you my opt-in rate is well below 1%. When someone installs and activates my plugin, the odds are overwhelming that the next “interaction” I have with them is when they click “update” in a few weeks on that plugin.

On top of that, even if a user does opt in on that settings page, my current system is painfully unsophisticated: I have one list for all subscribers. That list is not designed to be a means of communicating with existing plugin users. It’s designed (as I mention on my home page at least twice and every other chance I get) to educate.

Thankfully I’ve never had a breaking change with any of my plugins. If I did, though, my only option would be to stuff a lengthy explanation under the cushion and hope that you read it before you started mowing the lawn, Pete.

That’s one of the reasons I try to make my changelogs fun.

My thought is that if I make them interesting enough, more people will read them. And that means that holds hand over heart you’ll never see “Various Bug Fixes” on my changelogs.

Here’s a brief list of things developers can write in their changelogs in order of effectiveness from most to least:

  1. a random lyric from a Justin Beiber song
  2. random text like oiuw erlkj sdf;lk sdf;
  3. literally anything you can think of to type
  4. nothing at all
  5. “various bug fixes” with no explanation.

I promise to make my changelogs useful. If you are serious about your web site, you should commit to at least skimming them.

Similar Posts