james mckay dot net

Since I’ve released a WordPress plugin that’s been attracting a fair amount of attention, it’s inevitably had its share of users who have reported some problem or other. Most people find that everything proceeds fairly smoothly, but inevitably there will be those who, for one reason or another, simply can’t get it up and running. So I thought I’d put down some tips on what to do if you encounter a problem, and how best to go about reporting it.

This advice is intended to be fairly general, and not specific to any of my own plugins, and though different developers may have slightly different expectations, it should come in useful irrespective of which plugin you are using and who wrote it.

1. Make sure that you’ve read and understood the instructions.

This may sound obvious, but amazingly, some people don’t. Check that your version of WordPress is supported (most newer plugins these days require version 2.0 or later, and some even require version 2.1). Check that you’ve understood correctly what the plugin does, what all the configuration options mean, and whether or not you’ve overlooked something. There may also be some known issues or bugs with the plugin, so you should check to see if you’re up against one of those. It also helps to read the comments left by other users: they may be able to shed some light on the problem. A search of the WordPress support forums may also help.

You don’t have to trawl the whole Internet or even the whole site, but if you at least show that you’ve looked in the most obvious places, it helps a lot. If there’s anything you don’t understand, by all means say so, but indicate exactly what it is that you don’t understand, rather than simply saying “I don’t understand the instructions.”

2. Check to see if there’s a conflict with another plugin.

There are thousands of WordPress plugins out there, and it is simply not possible to test our creations against all of them. Consequently, there is always the possibility that your newly installed plugin could be conflicting with one of the others that you have been using.

Checking to see if this is the case is fairly straightforward, though it’s a good idea to back up your WordPress database before you do so in case anything goes wrong. Disable all your other plugins and switch to the WordPress default theme. This may or may not fix the problem. If it does, switch your theme back and then re-enable the other plugins one at a time until the problem reasserts itself. When you do this, the conflict is between your new plugin and the last one that you re-activated.

You should let us know which other plugin or theme, and which version, is causing the problem. Tell us where to get it too, and make sure that the link to its home page still works. There is little or no incentive to ensure compatibility with a plugin or theme that has vanished off the face of the web and is no longer being maintained.

3. Check to see if the problem occurs on other computers in other places.

Some plugins have features that depend on your IP address, which may be different depending on whether you are accessing the Internet at work or at home. Some have Javascript that may not have been tested thoroughly on all browsers. You may be accessing the Internet through a proxy server which could be causing unforeseen problems.

If you can, check to see whether or not you get the same problem on a different browser on another computer. You don’t have to check every permutation of plugins and so on, but if the problem occurs in one place and not another one, we’d be interested to know.

4. Make your feedback clear and specific.

Here is an example of a bad question:

I tried your plugin. I can not get it to work. What is the problem?

This haiku is worse than useless because it tells me nothing, yet I have to spend time reading it and deciding whether to respond to it or report it as spam to Akismet. If you’re lucky, you’ll get a response along the lines of: “I haven’t a clue. I am not a mind reader. Please give more details.” If you’re not, you’ll just be ignored and your comment will be flagged as spam.

By contrast, here is an example of a good bug report:

I’ve installed version 3.14159 of the Happy Pi Day plugin and I’ve found that my users are getting a Blue Screen Of Death when they visit my website on the fourteenth of March if they’re using Internet Explorer on Windows Vista. I’m running WordPress 2.1.3 on PHP 4.4.4 and MySQL 4.1. I’ve tried disabling all my other plugins and switching to the WordPress default theme, but the problem still persists. There’s an option on the plugin page that says “Einstein’s Birthday Mode” but I didn’t understand from the documentation what that is supposed to do, so I haven’t tried changing that.

You can see the problematic page at http://www.example.com/happy-pi-day/.

This is much better because it gives us a lot of useful information in clear, unambiguous terms.

At an absolute minimum, you should state:

• what you expected to happen;
• exactly what actually happened;
• the exact text of any error messages;
• the steps needed to reproduce the error;
• which versions of WordPress, PHP, MySQL and the offending plugin you are using.

You should also give as much additional information as you have been able to determine in your troubleshooting steps above:

• which browsers and operating systems are affected on the client side;
• whether you have found a conflict with any other plugins or your theme;
• anything about the documentation that you didn’t understand;
• where appropriate, the URL of a blog or post where the error can be seen in action.

Remember that you’re aiming for clarity. Write in plain English, in whole sentences. Read your report back to yourself to make sure that it’s clear and unambiguous. Don’t post guesswork as to what you think the problem might be: report the symptoms of the problem — i.e. exactly what you did, exactly what happened, and exactly how reality deviated from your expectations.

Many plugin authors — myself included — work on their offerings for free. This means that the amount of time that we can spend supporting them is strictly limited, and unless you are one of our paying clients, we have to triage bug fixes and support issues that come our way, sometimes pretty aggressively. Inevitably, it’s the queries that provide us with the most helpful information about the problem that are likely to get the most (and quickest) attention.

Comments closed »

Posted at 15:24 on 28 April 2007.
Tagged: contact, WordPress

A colleague of mine mentioned to me the other day that I ought to read The Mythical Man-Month by Fred Brooks. I haven’t done so yet, but I was interested to see from the various reviews that it talks about the “second-system effect” — that the second version of a system that you design will tend to be over-engineered, since it has all the features that you thought about for the first version but didn’t implement due to time constraints. It means going from a small, elegant, successful system to something large, feature-laden and bloated. Scope creep, in other words.

I’ve been thinking about this as far as the next version of my Comment Timeout plugin is concerned. The original idea was quite simple: to close comments on your blog entries after a certain length of time. The current version has extended well beyond that remit, with a whole bunch of other features that, while useful and maybe related from a technical perspective, aren’t really related from the end user’s point of view to what the plugin is ostensibly trying to do. I wonder if this is probably a bit confusing for users and making it a bit difficult to determine whether issues are due to bugs in the code itself or people misunderstanding what it’s supposed to be doing.

I think the answer is probably to separate it out into different plugins, each of which concentrates on doing a single thing and doing it well. At the moment, I’m thinking of separating it into three different plugins, perhaps something along these lines:

• Comment Timeout 2.0: a trimmed-down version, which concentrates solely on the job of closing comments on old posts after a certain length of time.
• The Black Hole: the functionality to nuke comments altogether if they contain BBCode, too many hyperlinks, or certain keywords, so they don’t even make it as far as your spam queue.
• Three Strikes and You’re Out: the bit that examines your Bad Behavior logs and spam queue and closes comments to IP addresses that are persistently causing trouble.

I’d be interested to know what people think of this idea. Would it make it easier to understand, or would it just make things a bit more confusing? Leave me a comment and let me know what you think.

Comments closed (6) »

Posted at 08:15 on 26 April 2007.
Tagged: Comment Timeout, Link Limits, second system effect, The Mythical Man Month, Three Strikes and You're Out

One of my tasks this week has been to roll out some changes to a fairly busy web application. Because it is pretty heavily used, when we make changes we need to get it right and minimise downtime.

How do you do this? Script the upgrade process. Ideally, you should be able to simply copy a working build to the production server, hit a button (or run a script) to switch from the old version to the new one, and you’re done.

This particular web application’s upgrade process is very simple. You get the code files from the build that you want to deploy and copy them onto the web server — into a new directory for each version, e.g. “html-3.14″. You change a symbolic link at the web application’s root that points to the version you want to use. You’re done. Rolling back — should things go pear-shaped — is simply a case of changing the symlink back again.

To get this working effectively, I had to streamline the application itself. Some files, such as site configuration, may vary from one server to the next, so I had to separate these out. I partitioned the application into three directories: the code, the configuration files, and dynamic data, such as logs and uploaded files.

Only the code directory changes between versions: its contents are exactly the same whether they are on the developer’s machine, the staging server or the live server, and it has no special requirements in terms of access rights or contents. Files that need to vary between different servers (such as configuration files) are kept in a separate directory and are not changed during a normal upgrade process. This makes the upgrade script very simple.

This explanation is probably a little bit simplistic, although it can easily be extended to take account of extra requirements such as changes to the database schema or addition of new configuration options. Some upgrades will also have much more complex requirements, but the general principle is the same. Script the upgrade process so that it runs in a single step. It’s the same principle as the one Joel Spolsky makes when he asks in The Joel Test, “Can you make a build in one step?” If you have to edit several files and jump through several hoops, the risk increases that you will make a mistake somewhere along the line. Being able to do it all in a single step is much more robust, and mostly seamless from the end user’s perspective, because if all goes well, they will notice no downtime, but only that there are some new features and some irritating bugs have been fixed.

Comments closed »

Posted at 18:06 on 24 April 2007.
Tagged: deployment, upgrading

The signs in stations on the London Underground direct you to platforms for a particular line heading in a particular direction — for example, the eastbound Circle Line, the northbound Jubilee line, and so on. The different lines are all colour coded — the Circle Line is yellow, the District Line is green, the Bakerloo Line is brown, and so on. With many platforms being shared by two or more lines, one would expect that the trains themselves would arrive indicating primarily which line they are running on, preferably with the same colour coding fairly prominent, right?

Wrong.

The trains themselves, and the notice boards on the platforms, indicate only which station is their final destination. There is no clear indication of exactly which line they are running on. When you are on a platform that is shared by two different lines, this can cause quite a bit of confusion if you are unfamiliar with the routes themselves, and, as is often the case on the Underground, you have only seconds to determine whether the train on the platform is the one you want or not before it closes its doors and heads off into the unknown.

Take what happened with the five of us who went up to MiniBar last night as an example. After some debate on the way back as to whether we should walk to Aldgate East or Liverpool Street station, we decided to head for the latter. At Liverpool Street, you head for the eastbound platform and take a Circle Line train. The Circle Line turns south then west after Liverpool Street and reaches Victoria after a dozen or so stops.

The train on the platform was the one for Barking. Okay, fine, where’s Barking? These trains stop for less than a minute, so rather than find a map and then look for Barking to see if this was the right line or not, we collectively decided to jump onto the train with only seconds to spare, and then ask questions.

We were halfway to the next station before we realised that Barking is, of course, at the end of the Hammersmith and City Line — i.e., heading in completely the wrong direction.

Not to worry, however. You get out at Aldgate East, cross over to the platform on the other side of the tracks, and catch the next District Line train heading west, arguing vigorously all the way about whose fault it was that you ended up on the wrong train in the first place.

The only problem is that you have the same problem on the other side. We had arrived on the platform and were scrutinising the map when a train came along. “Hammersmith via Kings Cross/St Pancras.”

The same individual who led us onto the wrong train in the first place now embarked on this one, and most of the rest of our party would have done so too, but for the fact that two of us had already figured out that this one was also operating on the Hammersmith and City Line, which does not go directly to Victoria, and would merely have taken us back to where we started.

Fortunately we managed to convince them to wait on the platform until we had determined which train was the right one before getting onto it, and eventually we ended up on the right train, but by this time, we were beginning to come to the conclusion that the game of Mornington Crescent bears a lot more resemblance to reality than originally intended.

Comments closed »

Posted at 09:06 on 21 April 2007.
Tagged: London Underground, MiniBar, trains