WordPress Plugin Guidelines

So this will probably cheese some people off since I don’t actually develop or release any plugins myself, but of late keeping up to date with plugins is a real pain in the ass for various reasons.

A lot of plugins are simply abandoned, or provide half-ass to no support, others only work in a small percentage of installs, some you have no idea what they do unless you actually install and activate it to see.

Because of all this there are a few basic guidelines that I think plugin authors ought to follow, and whereas I am by no means an authority or person of influence of any sort, I use a lot of plugins on quite a few different WordPress installs and these are some things I have noticed that should (in my opinion obviously) be more or less standard practice for plugins.

Also note that I am going to be using a couple of the plugins I use on this and other sites as examples in this post. They may be used as good or bad examples, or even both for different points, but there is nothing personal or derogatory intended. these are my opinions, and my views on problems I have had, I am not digging on the plugins, and I use/used most of these plugins and wouldn’t even link to them if I thought they weren’t worthwhile.

See my Plugins, Widgets & Themes Used on this Site page for a list of plugins I use here (and that are currently activated) and links to their sites.

Also note that while these are numbered, they aren’t ordered by any particular criteria other than the order in which I thought of them.

Also, although this is about plugins, a lot of these items can be just as easily applied to Theme releases.

  1. Include a live demonstration and screenshots of the plugin somewhere on the plugin page.

    This is ridiculously important, especially for any plugin that has any type of visible effect on the blog whatsoever, and yet so many plugin authors don’t bother. Go look through the plugins listed on the Codex, there are even Image and gallery plugins that don’t have any type of demo or screenshot whatsoever.

    How do I, or any other users know if they want to install a plugin if they can’t see what it does?

  2. Clearly list version numbers on the plugin page, in the documentation (if there is any…) and in the plugin itself, and if possible the release date of those version numbers.

    Again, so very, very important, but a lot of plugin authors simply post a zip file somewhere on their server called “latest version”. “Latest version” tells me nothing. Especially since in a lot of cases that “latest” version is months or even years old!

  3. Clearly state what WordPress versions that the plugin works with/has been tested on and what versions it has been proven not to work on.

    Not that hard I think, but a ton of blogs out there with posts that are undated, but have a plugin available for download, but when you download the plugin you find it was made for WordPress 1.5 and you can’t use it, or worse you try to activate it and it eats your blog. (In case that ever happens to anyone and you can’t access your blog anymore, just FTP to your site and rename either the plugin file/folder or the entire plugins folder and WordPress will automatically deactivate it).

    You don’t have to test it on every version of WP that’s been released, and you don’t need to explicity write whether it works or not for every, but please at least write what EXACT version(s) you have actually tested the plugin on. Don’t write WP 2.+ or something similar as so many plugin authors do. You don’t know that the plugin will work with any future releases of WP. Even plugins developed by people who are also working on the development of WP break when new versions are released.

    Often times a plugin only works with one specific WP version or subversion, but we can’t tell that without trying it out, or asking “does this work with 2.1?” if you don’t tell us. I know plugin authors hate getting stupid questions over and over in their comments and whatnot, but if you don’t provide the necessary information, then you’re going to get even more than your fair share of the stupid/irritating questions.

  4. Keep the number of admin menu items to a minimum or use submenus.

    I hate having to search through the entire WP admin menu to find the submenus for newly activated plugins.

    I hate it even worse when plugins have entries in more than one place (i.e. a config menu under Options in the admin panel, and another menu/set of options/controls under Manage or similar setups). Unfortunately some of my favorite plugins are guilty of this…

    Honestly, I think all plug-in interface menus should be under the same menu item to differentiate them from native WordPress functions, maybe under the Plugins link for instance?

    Even if you can’t stand putting your plugin menu under the plugin link and just have to stick it under dashboard, or comments or some other oddball location that deviates from the norm, then at least keep all the stuff for that plugin in one place. I don’t mind submenus, like MyGallery for example, where there is a MyGallery link added to the main Admin menu and then there is another submenu bar added underneath with the plugin Options, Gallery Management etc., when the MyGallery link is clicked, but having menus and options for the same plugin in 2 (or sometimes more!) places in the admin interface is just pointless, confusing and frustrating.

  5. Keep the plugin design as simple as possible (especially in the back end).

    I have seen a number of good plugins ruined by trying to make them fancier. I’m not referring so much to new/different functionality as I am to unnecessary embellishments (like pointless AJAX).

    Adding unnecessary effects, or bells and whistles just increases the chances that something is going to break or conflict with something else.

    Again, one of the plugins I used heavily up until 2.1 was released was WP-Amazon. The new version is in beta and it’s got a fancy new AJAX interface and looks really slick and everything, but honestly, I can’t see the point. The old version used a simple plain old HTML link at the bottom of the post window and a popup window, but it worked perfectly.

    If I tried really hard the only suggestion I could have even come up with for something to change would have been to have moved a “Back” link in the interface to somewhere more convenient. Other than that, absolutely no problems.

    New version, bells and whistles fancy shmancy, but not much of a change in the actual functionality (which isn’t a dig, it pretty much did/does everything it was supposed to and needed to), however it now causes problems on over half the sites I have tried installing it on, and isn’t working properly in the regular (non-visual rich) editor, which has rendered it completely useless to me.

    The new version WP-Amazon is still in Beta, and most of the problems I have had are flagged to be fixed in future releases, but I still think I’d rather have just had the basic version updated for WP2.1.

    Seriously, I like AJAX and scriptalicious and MOO FX effects as much as the next guy, but I really think a lot of people are adding this into unnecessary areas just for the wow factor (I am guilty of this myself) and it’s killing a lot of otherwise great plugins.

  6. Give your users somewhere to talk about and provide feedback on your plugin.

    Open the comments on the plugin post/page, create a forum, anything, just provide some area where the users can post comments about the plugin and hopefully help each other and view existing problems and solutions which might help them. I have found the solutions to most of my problems in the comment threads of plugins (not at the WP support forums, but that’s a whole different rant).

    I know a lot of plugin authors don’t want to provide support or deal with problems for their plugins, but honestly you don’t have to provide round the clock support for your free plugins, however if there is a significant issue that a large percentage/majority of users have it might be worth looking into, and if you allow users to talk to each other you might find that some have already found solutions (or at least causes) for problems that others are having. At the very least go open a thread on the WP Support Forums with a title “MY PLUGIN NAME Official Troubleshooting Thread” or something.

    Alot of plugins (Viper’s, Alex Rabe’s) even have their own forums.

  7. Please, please, include installation/activation/configuration instructions not only on your site, but with the plugin (a readme file or something, don’t care if it’s just copied and pasted from your website).

    Again, something that seems so basic and common sense, and yet a lot (I even want to say the majority) of plugins just don’t do this.

    I am not sure how other users handle plugins and website management and such, but I personally often times find new and interesting plugins by accident. Or I am looking for a plugin for a specific purpose but end up having to download a number of different plugins to test and see which provides the functionality I want in the manner I like best/that works best.

    In either case I often don’t install the plugins right away. Sometimes there are days or weeks between the time I save the plugin on my pc and the time I actually get around to installing/testing it, and let me tell you that it’s really annoying to finally have some time to mess with things and have no local directions, but when I attempt to access the instructions on the plugin’s website, the website is down, or moving, or I just can’t connect because of some internet hiccup or another.

  8. And, although I hate to see good plugins disappear, if your plugin is abandoned, but you still have a website up for it, please, please, clearly state that the plugin is abandoned.

    I can’t count the number of times I have found a plugin I liked only to find that the author has commented on it, replied to any comments on it in over a year, or asked a question in the comments only to be told “I no longer support this plugin”.

    If that’s the case, fine, free world and everything, but could you at least post somewhere up near the top of the page “This Plugin is Abandoned/No Longer Supported”. It would save me (and I’m guessing others) a lot of time and trouble, because I personally usually won’t even bother with abandoned plugins.

Notice I am not harping on overall documentation too loudly. As someone who makes his living dealing with documentation (I do translation, copywriting, and proofreading work for a living; I don’t generally bother proofreading anything I put on this site because this is a hobby, the quality level of actual paid work is a lot higher =) I understand how much of a chore it can be, and how really detailed documentation can actually take almost more time that the actual coding. Do, however, include the basic required information (if a php call is required to activate the plugin, list that php call somewhere, etc.).

There’s a bunch of other stuff that I just haven’t remembered at the moment, and things I’ve never really considered. Comments are open, feel free to add stuff or comment.

preload for rolloverimage please ignore preload for rolloverimage please ignore preload for rolloverimage please ignore preload for rolloverimage please ignore preload for rolloverimage please ignore