This post is dedicated to Lisa Sabin Wilson, who donated to help me get to WCSF. Lisa is to documentation what I am to the forums, and encourages me to write better (though she probably didn’t know that).
Quite often people suggest that we ‘weigh’ the usefulness of plugins and themes in the WordPress repository differently. Some want to use star ratings, other popularity, and others compatibility of WordPress Versions.
Invariably, if I get roped into these discussions, I say ‘None of it maters more than the rest.’ And people always argue that their chosen method is the best. No one has ever succeeded in convincing me they’re right and, I’m pretty sure, no one ever will.
The reason I’m so sure about that is the same reason we don’t just buy cars based on the tire size, or a house based on a bathroom. It’s the reason we research and compare, study and inspect, and ask our friends. It’s because we know to look at the big picture.
Let’s look at A Sunday Afternoon on the Island of La Grande Jatte. From afar, it’s simple. A painting of people on the island. But if you walk up to the painting (it lives in Chicago, I love visiting it) you’ll see Seurat painted entirely by dots! As you step in and out, the painting changes and your perspective and understanding of the work as a whole changes. You cannot simply say ‘There is blue paint.’ and make your final decision that this painting will look nice against a blue wall. You have to consider how it will look up close, far away, and will it be better to blend or contrast. Seurat liked the contrast, which is why it has a brown border and a white frame.
The small moments, those dots, make up the whole of the piece and you have to consider everything that went into it, if you want to understand the painting. Anyone can look at if from afar and say ‘Yeah, nice.’ But when you start looking at the work, and the layers of meaning, you see things differently. With art, that’s the point. Sometimes a painting is just a painting, and sometimes a story is just a story, but more often than not, the ‘deeper meaning’ your teachers were after you to get from a story is simple: Look at the whole story. Look at how each character’s actions become a part of the whole.
This relates, directly, to understanding plugins. At heart the question people are asking is simple: How do I know which plugin is the best to use for this situation?
You can’t just take one and say ‘This is compatible with 3.4, therefore it is superior!’ I wish you could, my life would be easier. Instead, you must learn how to review plugins critically. Don’t throw your hands in the air, you don’t need to know code to do this. You do need to know what you want, and you need to read and pay attention, but at this point, if you’re still reading this blog post, you know how to do those.
The secret magic, which I talk about in WordPress Multisite 110 (Chapter 6: Security, Plugins, pg 36), is to review all components of a plugin’s information. You have to look at how all the little dots make up the whole picture — that’s why we talked about Seurat — and use those to understand how likely a plugin is to be safe to use.
Who wrote it? If I see a plugin written by someone I’m familiar with, I’m more inclined to trust their work. I already know how to get in touch with the developer if something goes wrong, and we have a rapport. Second to that is if they work on WordPress core. If they have commit access, I trust them (even Otto, who’s broken the site before). If they’re a regular contributor, it’s much the same. However this is not ‘common’ information. It’s easy to find, but it’s not something everyone knows off the top of their head. You can quickly search trac for their user name. I find it easier to limit the search by changesets, so here’s a search for wpmuguru’s credits in changesets. Yeah, looks like a trustworthy fellow!
What does their website look like? In cases where the developer doesn’t have any core contribs, move on to look at their website. Is it the generic version of WordPress with barely any content? Is it a Geocities flashback? You know crappy websites when you see them, and a crappy website for a developer warns me that they don’t use WordPress the way I do. Little to no content implies they’re not writing posts, and if they aren’t writing posts, how do they keep up with the look and feel dynamic of WordPress?
Is it well documented? Documentation is king. A plugin that is poorly documented, with poor spelling and grammar (regardless of language), and no screenshots makes me Spock the eyebrow. Not every plugin needs a screenshot, but a plugin should have the basic information included on that page. I’ve started copying my readme content into the contextual help in my plugins, for extra documentation levels. The point is, if the documentation is sparse, either the plugin is really simple, or you’re going to have a bad time of it when you have a problem. Developers, document. It will save you a lot of time.
How often is it updated? This is where we start to get weird. The simpler a plugin, the less it needs to be updated. Impostercide has barely changed since WP 2.5. I do update it about once a year, to change the versions, or add internationalization/help screens, etc. The bones of the code have not changed since 2005, and the original version still works just fine. Not every plugin should be updated every month. Now a more complicated plugin, I’d actually like to see it updated more often, with smaller changes. Don’t change it all at once, after all. Review the Changelog (if they don’t have one, it’s not well documented). See what’s being changed.
What problems have people had? Recently the Andy/Otto team made it easier to see the forum posts associated with a plugin, which means it’s easier for you to see how active a developer is with support, and how problematic the plugin is. Many of these issues are user-based (i.e. they’re not sure how to use a plugin), but sometimes they’re actually bugs. Check how many problems have people had, and if they are resolved. This example is a great sign:
What’s in the Compatibility Matrix? This is a very complicated thing, but it’s also very telling. Knowing how many people have reported a plugin works or doesn’t work, and getting an average, can help you. Sometimes you have to go back and forth, checking various plugin versions to WordPress releases, to get the whole picture, though, so it can time time to understand what’s going on.
What Else? Only now do I take a look at things like downloads, what the author says it’s compatible to, when it was last updated, and what the stars are. Why? Because unless an author has written ‘This plugin will not work on WordPress 3.4!’ in the readme, there’s a darn good chance it’s just fine and they didn’t bother to update. And that pisses off a lot of people.
Look. There’s no feasible way to force the developers to update their plugin documentation right now, and even if we did, there’s no way to assure they got it right! People make mistakes, which is why we have to learn to use our brains and think about what we want to do before we act. Yes, it’s work. As I’ve said many times, running a website is work. It’s always going to be, so at least try to work smarter.
I didn’t touch on code reviews at all, but what tips and tricks do you use when you’re collecting all the dots and evaluating a plugin for use?