WordPress documentation – a step backwards

I don’t like the switch to https://developer.wordpress.org

The documentation is noisy and full of bad examples. In the past I remember searching for quick reminders on WordPress functions on how and when to use them, and landing on really useful pages. The information was right there.

Now there’s just a copy of what’s in the code, some abstract software-correct machine driven parameters, lots of drivel that’s of no use to your average WordPress developer, And then follow some examples that always fail to answer what I’m looking for.

It probably looks super useful to core developers/committers who think it provides a wealth of useful information. But WordPress’s success has been to enable the day-to-day WordPress developer – no matter their WordPress involvement – to achieve their web development goals. And this latest iteration on documentation fails to do that.

Getting started with WordPress development

If you already have some programming skills (especially if you are familiar with PHP), and are looking for resources on how to get stuck into WordPress development, then the old idea of sticking your nose in a text book is probably not your best approach.

Text books do quickly go out of date, and are probably better for absolute beginners. Especially in an environment where you are working and creating on the internet. Obviously, your best resource is a the internet itself.

So, here are my top tips for getting started. Yes, it’s a bunch of reading, but it is also a fantastic set of resources that I still reference now:

Should all WordPress Plugins have a Database Schema Version?

Should WordPress plugins that make any database schema changes have a local database scheme version number?

The plugin README file has tags for Requires at least, Tested up to and Stable tag.

I’m suggesting that alongside defining the plugin version, and the three README tags, there should be a value for the schema. This means that plugin authors can explicitly note when their plugin is updating the schema.

Whether it goes in the main plugin file next to plugin version, or in the README file I’m not sure it makes any difference. But if we build in some hooks to trigger on schema version change then we gain two things. Firstly, developers like it as they can explicitly perform tasks based on schema versions and version changes. And secondly, users can be notified that the plugin is about to make schema changes. Which might encourage backups.

I think that’s a win-win!

What use is the WordPress register_activation_hook() function?

Having been playing around with WordPress Network (Multisite) plugins, mostly internal, not doing much that anyone else would be interested in having. During a plugin’s lifetime it goes through some critical points. The one you can’t avoid is activation. Many also experience deactivation or even deletion. Most will, at some point, be updated. for these critical points the plugin author may want to have certain critical events happen. Setting up options, creating databases, pre-populating meta data. And of course the reverse – deleting said litter.

A quick summary of the register_activation_hook() function:

  • It doesn’t work on multisite. Network activation does not trigger this function
  • Updating the plugin does not trigger it
  • It is triggered every time a plugin is manually re-activated

None of these are my desired behaviour. I usually write my own hook that checks if the plugin version has changed, and fire off my actions.

Which makes me wonder whether the function is out dated, and should be replaced a set of alternative functions. They could perhaps even be actions?

  • register_plugin_activation_hook
  • register_plugin_network_action_hook
  • register_plugin_update_hook
  • register_plugin_update_network_hook