I visit the WordPress Plugin Directory a lot during my constant hunt for plugins for our release posts. If you’re a plugin author and you’re not hosting your plugin on the Repository then you’re definitely missing out a lot in getting your plugin out to all WordPress Users, especially now with the Plugin Directory search improved. So, if you’re a plugin author and if you release your plugins as GPL, then do remember to add your plugin.
That being said, if you’re hosting your plugin there, then you will be required to add a readme.txt file in the folder of your plugin.
To begin with, take a look at the standard readme.txt file.
The readme.txt file contains the following sections:
- Plugin Name
- Description
- Installation
- Frequently Asked Questions
- Screenshots
- Other sections
In my opinion, the most important of these are the first two sections since these are the first that a potential user sees. Completing all the sections is also useful since these can be searched.
I’m going to focus this post on the Plugin Name section.
=== Plugin Name === Contributors: Ajay, Mark Ghosh Donate link: http://weblogtoolscollection.com/ Tags: comments, spam Requires at least: 2.0.2 Tested up to: 2.1 Stable tag: 4.3 Here is a short description of the plugin. This should be no more than 150 chars. No markup here.
Another important section while adding your plugin is the header section in the plugin file itself. Here’s the section from my plugin Top 10.
/* Plugin Name: Top 10 Version: 1.1 Plugin URI: http://ajaydsouza.com/wordpress/plugins/top-10/ Description: Count visits per post and display the most popular posts based on the number of views. Author: Ajay D'Souza Author URI: http://ajaydsouza.com/ */
And, while this isn’t part of the readme.txt, it also contributes towards the listing of your plugin. These both, in combination, are used to populate the details for each plugin as you can see below.
The Author Homepage and Plugin Homepage are pulled from the plugin file, viz. Author URI and Plugin URI respectively. The version number is also pulled from the plugin file. The Requires WordPress Version, Compatible up to and Donate link are pulled from the readme.txt file.
Hence, populating both the readme.txt file and the plugin file make your plugin complete.
I’ve seen a lot of plugins which either miss out one of the three links above or just point them back to the repository. Some plugins have the same Author Homepage and Plugin Homepage. Needless to say, these aren’t making the most use of all the sections that are given to you.
Are you a plugin author? Are you hosting your plugin on the directory? If so, why not?
Are you ensuring that you are completely using all the sections in your plugin header section and the readme.txt? Do remember to run your readme.txt file through the validator.
As a WordPress plugin writter, I always make sure readme.txt complies with the standard. The validator tool provided by WordPress is a easy-to-use tool to check for the validity of your readme file.
Best thing you can add to your plugin’s readme.txt is decent tags. Really helps the plugin search find your plugin based on those keywords.
Unfortunately, even if a plugin author fills in the required information for their readme.txt file, it will not necessarily tell the users everything they need to know.
While WordPress runs on MySQL 4 and PHP 4, a lot of writers develop their plugins on MySQL 5 and/or PHP 5. There is nothing wrong with this, but it means the plugins may not run on earlier versions. Too many writers do not mention that their plugin was developed for the newer versions and may not work on the earlier ones. That is something I wish the readme file asked for.
It may be a bit pedantic, but technically if the requirement for WP 2.7 is PHP 4.30 and a plugin doesn’t work with PHP 4.30, then it’s not compatible with WordPress 2.7 even if it will sometimes work on that version in some situations and setups.
Good luck convincing the plugin writers to put that in their readme.
“Compatible with 2.7?” “No” “Why would I want it?”
PHP is not supporting PHP4 anymore and WordPress needs to drop PHP4 support very, very soon. But because of the lazyness of some hosting companies that refuse to upgrade from obsolete software version PHP4 is still in use, even the fact is that if something goes wrong there is no one to fix the bugs in it anymore.
That is true. But until WordPress bites the bullet and actually requires PHP 4, it would be nice for the writers to let the users know that there may be problems trying to use their plugin.
From a serious blogger point of view too often authors are making very good use the readme. I don’t have time to hunt down a bunch of information on their blogs, that is only alluded to in the install or description. I understand writers want people visiting their blogs especially when they run ads, but not having all the information a person needs to configure a plugin in the readme file is ridiculous, in fact it just pisses many people off. I can’t begin to tell how many times I scrapped what looked like a good plugin for something else that came with the right kind of install/configuration info.
Another thing I would like to see plugin authors do is to write their copy paste function calls as if function exists calls. This is a problem that flummoxes many noob bloggers when it comes time for that inevitable deactivate all plugins to find the conflict.
I’d also like to ask/request that all plugin developers put the installation/usage directions in the readme.txt, not a link to your site. It’s kind of irritating seeing “Visit xyz.com for installation instructions,” especially if the site is down or slow. Instructions should be included in the readme.txt
Sometimes instructions can be complicated and benefit from screen shots and step by step guides. I know I take a lot of effort on the writing the instructions for my plugins and they just won’t work or look right when converted into readme.txt format.
If you can’t be bothered to actually visit the website of the person who put so much time and effort into writing the plugin that you want to use then… well I don’t know what to think.
I didn’t say that I couldn’t “be bothered” to visit the sites. But it doesn’t do much good if the site is down or takes forever to load because the page has hundred or comments on it.
One trend I’ve noticed is the use of .pdf documents with the instructions. They are convenient and essentially free to create using a program like Cute PDF: http://www.cutepdf.com/
I find it a lot more convenient when the instructions are readily at hand. I realize that most plugins are developed and made available freely, but if plugin developers can’t be bothered to make things easy for their users then… well I don’t know what to think.
“page has hundred or comments on it.” Should be hundreds of comments on it.
It isn’t so much that we get detail instructions in the plugin readme file, just sufficient instructions. I have no problem what so ever going to a site for the complex, advanced, and/or modified instructions. Hell, I will even click on ad and be glad there are advanced instructions. That said there should be basic enough instructions on how to install and add the plugin to a theme template.
I would be happy if the instructions said:
“upload, activate, configure in settings, and install widget. See http://pluginsite.com for step by step configuration instructions”
However when all you get is a link to the website and only get a php function call after wading through half a dozen ad filled pages it is not worth out time.
It’d also be nice if the plugin authors would indicate what’s different in upgrades. For example, a new version of WP Stats is out. Clicking the link displayed on my dashboard doesn’t seem to take me anywhere explaining what’s new or why I’d want the update.
I couldn’t agree more on this point. Whilst I habitually apply updates as and when they appear, a changelog either as part of the readme file or elsewhere in the information should really be a must. Even if the changes are limited to typos or extra translation features, it’s important to be able to spot when those annoying bugs are rectified, or when security holes are plugged.
Most plugin authors provide links to the instructions and information on the plugin, others (such as automattic) just provide a link back to the plugin page on the repository.
For plugin authors just getting started, I created a series of screencasts that walk you through the whole SVN process for getting you plugin hosted on WordPress. It may just be me, but it took me a while to figure out SVN. This might help somebody out there(it uses Aptana as an interface to SVN):
Screencast for hosting WordPress plugins with SVN