Expectations and Reality – The importance of documentation

Estimated Reading Time: 3min

Last week an uproar went through the WordPress community following a vulnerability in the widely used “WordPress SEO by Yoast” plugin and a subsequent forced update.

I’m not going to go into the (technical) details of this event here as enough has already been said about the facts and my point is a different one. Please follow the provided links if you want to read up on the whole story.

For most this whole controversy boils down to a general fight for or against automatic background updates, opt-in and opt-out and the 80%/20% principle that governs WordPress development. Some people got really emotional and angry about this. I’ll have to admit: Me too.

Now that I’ve slept over it and calmed down a bit I’ve come to the realization that the actual issue has been lying somewhere else:

The documentation was wrong.

Although fortunately it has already been updated by now (Thanks to the community for reacting quickly) the Codex until last week stated the following:

By default, only minor releases – such as for maintenance and security purposes – and translation file updates are enabled on most sites.


Automatic plugin and theme updates are disabled by default.

I remember that I’ve personally been to that site, read it and then, based on the facts I’ve read, made an informed decision about how the automatic updates work and what the defaults are. And there lies the problem:

I only thought I had made an informed decision.

But I wasn’t. This was disappointing to say the least. I felt betrayed. The way it came across was that someone ignored my choice and made unauthorized changes to a WordPress install I control. A self hosted install I’ve actively chosen to be such because I’d want full control over it. Doing that just has to be seen as one of the most invasive things that can be done to a WordPress install. And I think that was the way a lot of other people felt too.

Now imagine the Codex would have said what it says now ever since the automatic update feature was released:

In special cases, plugins and themes may be updated.


By default, automatic background updates only happen for plugins and themes in special cases, as determined by the WordPress.org API response, which is controlled by the WordPress security team for patching critical vulnerabilities.

Me and a lot of other people would have read that. I would have known the facts, might have decided to disable the plugin updates anyway and happily went my way. Last week I would have manually updated as I always do and everything would have been as expected. For all the normal users the 80%/20% principle would have set safe defaults and everything would have been all the same. Any we all would have lived happily ever after.

The lesson?

So what can we learn from all of this? I am once again reminded of how important it is to care for proper documentation and to do everything you can to never disappoint or betray user expectations. And at least personally it also reminded me that WordPress isn’t only the code in core but a lot of other things.

Finally it has led me to my first edit of the Codex. And when I’ll come across other errors or inaccuracies in the Codex I’ll just fix them. So to wrap this all up, at least for me there even has come something positive out of this whole issue.