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.

WordPress Network (Multisite): Always Specify Full Path for Includes

Recently I’ve been working a lot on network installations of WordPress. During development I won’t always adhere to best practices from the go-get. I’ll use little short-cuts. They let me know if something is going to work or not.

One error that I have come across, is a weird little thing that only happens under certain circumstances:

This happens if you include a plugin file that requires() a file in the same directory, and then browse to network admin. So, it works in normal admin, and it works if you require() a file from a different directory. But not in the same directory. It’s simple to fix, and is something that should be done for any beta or production code anyway..






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:

Change WordPress Admin Bar text ‘Widgets’ to ‘Sidebar Widgets’

The word ‘widgets’ is a little vague. To an every day person, it could be anything. For British of a certain age it might bring memories of an old advert. Even WordPress experts are aware that the word is often used to use different things.

So, renaming them to ‘Sidebar Widgets’ (because they go in the sidebar) is a small UI improvement that seems to make sense.


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!