Whether it’s guidelines changing or the codebase updating, there’s a lot to keep on top of as a plugin developer. One thing that never changes is the need to keep your users happy.
In this article, I’m going to draw out a number of things that we, as plugin developers, should make sure we’re doing. I’ve spoken to people on social media, in Slack (including the core support and plugin review teams) and even in person (thank you, everyone at WordCamp Europe 2023).
Avoid aggressive promotion
Whilst some plugins are written and supported for the sheer love of it, a lot exist for the purpose of up-sell – gently pushing the user towards a premium version of the plugin or another product entirely. But what is added to the plugin to achieve this can make a huge difference. Indeed, in the feedback received, getting this wrong can lead to the single biggest annoyance for users.
And the primary cause of customer chagrin are banner ads that appear in WP Admin, using the Admin Notice functionality. Often appearing as soon as you activate the plugin, they add an immediate “Please buy” to a user dashboard.
According to the WordPress.org plugin guidelines…
Advertising within the WordPress dashboard should be avoided, as it is generally ineffective.
If you’re going to do this, I would recommend a few basic things:
- Make it dismissible. Totally dismissible. Not for 12 months, or whatever.
- Make the layout standard – make it an information notice, full width and use an “x” button for dismissing it.
- Ensure you’re using the Admin Notice method for your banner. I’ve seen one plugin that uses its own JavaScript banner, which encroaches on the block editor, but also conflicts badly on other screens that use JavaScript
Sometimes they’re not even advertising premium products. One developer has a banner that they add to their plugins which advertises their other free plugins. The banner is tall, as the advertising covers many different plugins, and, if you have multiple plugins installed by the same author, each plugin puts up the same banner. So, always consider users may have multiple installations as well as the real-estate that you’re using.
Indeed, many banners that appear upon installation aren’t even advertising at all, but often are there to direct you to settings that you need to complete. Even these are not always warranted and the sheer number, mixed with the ones I’ve mentioned above, can generate bad feelings with users.
Equally, you need to think about which screen you’re placing them on. Most will be put on the dashboard, but some plugins will add them to their settings screen. Again, I am going to refer to the Plugin Guidelines…
Users normally only visit settings pages when they’re trying to solve a problem. Making it harder to use a plugin does not generally encourage a good review, and we recommend limiting any ads placed therein.
I truly understand the need to advertise – you have a product to promote, after all. But, once you drill down into a user’s annoyance, it’s rarely the fact that you’re doing it that’s the problem but how it’s implemented. It’s therefore important to be thoughtful and considerate.
Make your menus consistent
And, by “consistent” I mean with WordPress itself.
The temptation is to use admin menus to make your plugin stand out but more often it makes it harder to find and, worst still, breaks accessibility. For example, you should use the default CSS coloring and an SVG icon for your menus – if you override these, then if a user changes the WP Admin color scheme, which may be for accessibility purposes, then your plugin is unlikely to adjust accordingly. I’ve seen lots of examples of text and icons which are unreadable due to this.
If you create a main menu item, re-evaluate whether it’s actually needed. Help should go within the individual screens (make good use of WordPress’ help tab), settings and tools under the appropriate, existing menus. Most plugins have the need for just one screen, and that’s for settings (and, of course, if you can, try to put them into existing settings screens). Don’t invent the need for more so you can justify a top-level menu. They add clutter to the admin, and confusion where things aren’t where the user expects them to be.
Equally, positioning is important. If you do create a primary menu option, where should it be that makes most sense? If it’s to do with media, then maybe beneath the existing Media menu.
Try to keep your UI consistent
Whenever I create a plugin and, particularly, when it has any screens, I try hard to make sure that they match how the core WordPress experiences looks and feels. My target is always to try to make the user feel as if this were something that actually came with core.
Many plugins will come with something radically different, from buttons to the entire look of the screen. Some even break out of the WP Admin entirely, presenting their screens without the admin bar and sidebar. Similar to the last point, this is often something that’s done to make a plugin stand-out, but the reality is that creating your own UI for your plugin makes it more difficult for your users to understand. The majority of screens that you use in WordPress will make use of the standard UI so, suddenly dropping into one that doesn’t, breaks the simple-to-use experience. And, as with the menus, can break accessibility too.
More and more users are put off WordPress because of the admin experience, as a direct result of what some plugins do to it. Wherever possible, make use of the plethora of APIs available – they make implementation of screens a lot easier, and give a consistent look and feel to what you do.
Don’t put obstacles in the user’s way
Before I did my talk at WCEU this year I asked users what frustrated them the most about plugins. Yes, banner advertising was the top one. But, surprisingly to me, deactivation surveys were also popular too (or rather, unpopular, if you know what I mean). If you’ve not seen these, they are pop-ups that appear when you deactivate (not uninstall!) a plugin, asking you why you did so – think of them as the plugin equivalent to unsubscribing from an email list. It’s not a built-in feature but something that more-and-more developers appear to be adding to their plugins. I understand the need to know the “why”, but when you just want to deactivate a plugin (which may simply be being done for the purposes of debugging a site issue), it can be deeply frustrating to have this put in your way.
Indeed, in the screenshot below of a deactivation survey pop-up , temporary deactivation whilst trying to fix a problem, is one of the options you can choose for why you’re doing it, so the developers are acknowledging that this occurs…
Feature pointers were introduced into WordPress to provide an easy way for plugins to highlight options, upon activation. But I’ve seen some plugins that use them in such a way that they totally take over the admin screen until actioned – this is often the case when an action has to be performed after a plugin is installed (e.g. setting an API key), so the developer feels the need to make sure as little else can be actionable until then. Similarly, I’ve seen plugins that, once activated, will send you straight to their settings screen.
Your plugin should not take over or force the user into doing what you want them to do, but provide guidance and help which, if they want, they are free to ignore.
Keep “bloat” to a minimum
Whether it’s adding features unrelated to the purpose of the plugin or loading scripts when they’re not needed, you need to keep an eye on “bloat” – providing more functionality to your plugin than is actually needed. Features that are even related can be a frustration if they seem to be being added simply for the sake of “we need to add more to our plugin to look like we’re doing something”. Users love a slick, streamlined plugin that does what it needs to do and little else.
If you load scripts, whether front or back-end, make sure you only do so when they’re actually needed. For example, if a front-end script is only needed if a post makes use of a certain feature, only load it if that feature is used (which, I know, seems a pretty basic concept, but you’d be amazed how many plugins fail to do this – it’s far easier just to load it on each page load). Equally, don’t load scripts in admin when they’re only needed on the front-end.
Also, make sure to compress images and scripts – it’s often just assumed that this will be done client side, but it’s best to just do it in the source. Scripts – both CSS and JS – can be minified, and any image assets should be compressed. Often forgotten are your plugin assets, as included with a wordpress.org directory listing – plugin icons, backgrounds and screenshots all could do with a quick squeeze in advance.
Clean up after yourself
Plugins will often save settings in the options database, they may make use of transients to cache data, and they may even create their own database table as well. So, it’s important, when a user uninstalls a plugin, to remove all of this.
There are two ways to do it:
- Use of register_uninstall_hook to run a housekeeping function when the plugin is uninstalled
- In your plugin’s root folder, create a file named uninstall.php and place the clean-up function within this
In both cases, these will be actioned when the plugin is uninstalled and NOT just when it’s been deactivated.
Keep an eye on “the basics”
There are several things which I really don’t need to dive into the details of to explain – they’re the “basic” things that every developer should be doing but, sadly, often forgets. These include:
- Accessibility standards
- Just do it! Accessibility is something that should be fundamental but is so often forgotten. This is something that I definitely need to focus more on too.
- Translation
- Make sure your plugin is fit for translation, with the built-in Internationalization functions that are available.
- Data validation
- As Mika Epstein, from the WordPress plugin review team, said: “sanitize early and escape late. oh and use a nonce!”. Users aren’t going to be happy if your plugin is being reported for containing a vulnerability that could have been easily avoided. Learn more about WordPress nonces in Understand and use WordPress nonces properly.
Check your code quality
There are many tools available for checking code quality, and if you’re not making use of these then you’re missing out. How will not doing so put off users? Simply because not doing so is likely to lead to a lot of the things we’ve already discussed – users can be great at spotting the things that you may miss.
I would particularly recommend using PHPCS for scanning your PHP. There are rulesets available specifically for WordPress, as well as some for PHP compatibility too (your plugin working on the latest, shiniest version of PHP is something that’s likely to delight your users!). You can even integrate it into the most popular IDEs as well – it will scan and report as you write your code!
You should also consider checking any HTML output with various online validators, such as those available from W3C.
Props to @webcommsat @greenshady and @bph for reviews and @cybr for highlighting an issue in the original post
Leave a Reply