Because unless you’re active in the Philly WordPress community you’ve probably never heard of me. I’m not the author of a popular plugin, I haven’t written any books on development, and if you check out my Twitter account you’re going to find more about my theater activities than insights into WordPress development.
So, here’s what you need to know: I recently wrapped up eight years as a one-person “Department of WordPress” at a major university, where I administered several multisites, developed the operational strategies for the bulk of the campus web presence and functioned as a research and development unit. Besides building several custom themes and a couple dozen plugins of my own, I downloaded and tested literally hundreds of plugins from the WordPress repository to figure out which ones suited our needs and played well with others— to the point that I built a database to keep track of which plugins I’d tested, what version it was, their intended use and what I learned about them.
So, the advice I’m offering here is not from the standpoint of a WordPress expert of any kind. It is the insights of a potential user of your work who has also been where you are as a developer. I’ll focus mostly on the non-code aspects of development. I’ll be talking mostly about plugins, but the advice applies to theme development as well.
We’ll start with one of the toughest challenges for new developers: keep it simple. Maybe you’re at the point where you just created your first plugin or theme. And it works! And you’re excited, and a whole new world of possibilities has opened up, and you want to do them all. You’re already picturing all the different features and settings you want to add.
Before you do that … don’t. Identify clearly what you are trying to accomplish. If it’s a package of several things, then map out a plan and introduce a little at a time.
One useful way to think of your plugin or theme is as a section of a quilt that includes WordPress core and everything else that’s installed. For a site administrator, the goal is to neatly assemble these pieces that will produce the exact size and design of quilt that they want, neatly fitted together without gaps, extra pieces or bunches in the cloth.
You want your plugin or theme to be able to provide this piece, or a section of closely related pieces, to the whole. If you try to fit the whole quilt into your plugin, or you try to provide disconnected pieces, you risk making your product *less* rather than *more* helpful to users.
I ran into a specific example a couple of years ago selecting a new plugin that could hide or show widgets on different pages. The plugin I preferred was great, but: it also assigned a custom capability to manage user access to widgets. Which, in itself, is also great, but if you’re on multisite and have 250 sites to contend with and hundreds of users whose access you then need to update, this is not a small addition. It would have been better if these two seemingly related things — they’re both about widgets, right? — had been in different plugins.
I’ll give you another example from a few years back when the Exclude Pages plugin aged out. The plugin added a checkbox in a page meta box that would let you keep a page out of menus and page lists. There was no alternative in the repository at the time, so I wrote my own version.
My plan was to release it to the repo, but I also wanted to add more checkboxes allowing a content provider the ability to hide the page from the Relevanssi plugin’s search results and also from the XML sitemap plugin that we were were using. This combination was very specific to our setup. So what I decided to do is build this functionality as two separate plugins. The Exclude Pages Relaunched plugin contains a hook that enables you to add other checkboxes or options to its meta box. The Exclude More plugin hooks into Exclude Pages Relaunched to add those extra very specific checkboxes, along with the related validation and options handling.
But … keeping it simple doesn’t mean skipping over the less interesting parts of your work. You can get so wrapped up in plugin functionality or theme design that you overlook the elements that will make your product better. Do the secondary parts well, too.
This is a partial list of details that may escape designers and developers but be essential to admins. If you’re developing for a closed environment, your situation may be different. For instance, because my in-house development was solely for English and we were understaffed, I never bothered with translations or right-to-left layouts. For some some things, such as a robots.txt plugin I wrote for multisite, I skipped building an admin interface entirely because we didn’t want anyone but myself and the sysadmin configuring robots.txt.
The important thing is that this a choice appropriate to the context, not an oversight.
I’d add that the lack of accessibility compliance is becoming more and more of a dealbreaker for potential users of your work. If you’re creating something that might be useful to education or government in particular, you need to ensure any interface is accessibility compliant.
There are two things I’m going to point out separately. The first is that in the root of your theme or plugin directory, and in every subdirectory, you should include a blank index file if you don’t already have one.
So, why is this important? Over the past few weeks I’ve been helping a friend redesign her site for young children’s dance and storytelling classes. One of the steps was to ensure she was set up on Google Analytics and Search Console.
For several years she’d been using a nice theme called Hipster, which Google had been crawling.
When I checked Search Console, you know what her site was coming up for? Hipster images. Nineteen of the top two dozen search terms related to her site were about hipsters.
In my friend’s case I moved her to a theme that contained index files, and six weeks later Search Console was showing a major improvement in the relevance of the search terms to her site.
Google has become as intrusive as bad bots when it comes to crawling parts of your site that are not public content. And apart from serving up a site for search terms that have nothing to do with the content, Search Console is flagging templates and other elements as bad pages. I’m still having trouble with a map plugin’s templates files being flagged for not including viewport information — which they shouldn’t.
The other thing I want to talk about is the uninstall.php file. Please clean up after yourself. If you add anything to the database, or files that live outside your plugin directory, and these have no use when your plugin is not installed, at least give the site owner the ability to clean those out as part of the uninstall process.
When I write a plugin for public use, I add an uninstall.php file even when there’s nothing to install, I include the comment “nothing to uninstall” so that someone checking my work knows what to expect.
Speaking of uninstall, that leads us to the one special use case you may want to consider in plugin development because it’s part of WordPress core. That’s multisite. Unless you include code to loop through every site to perform cleanup, the uninstall file will only clean up the root site and leave entries behind on all the others.
This is also an issue on activation. If you network-activate a plugin and any setup routine in your plugin does not loop through all the sites, the setup will be performed on only one site.
You may think that multisite isn’t all that common and not worth bothering with, but consider: a single install may represent five sites, or it may be a hundred. Or 10,000. One bad uninstall may mean extra cleanup for 9,999 sites.
Multisite is enormously helpful in environments such as universities, and not developing for it is potentially missing an opportunity.
By the way, I’ve learned that by developing a plugin or theme for for multisite first and then testing it on a single install, I work more efficiently than I would by doing the reverse.
Finally: be kind to your users — which covers a lot more than being polite and helpful on the support forums.
This is another partial list of details to consider that are specific to the back end. Earlier I used the idea of a quilt to describe how the pieces of a site fit together. The admin interface is the other side of the quilt, and it’s equally important.
For those of us who need to deliver an easy-to-maintain site to a client, or provide managed hosting on multisite, the goal is to make a lot of disparate pieces blend into a whole, and the things you do to make your product stand out make our jobs significantly harder. You added submenus to promote your add ons? I have to remove them. That admin notice that can be dismissed with a click? On a large multisite, that’s 10,000 clicks, and so I either have to write scripts to close them or add a custom admin stylesheet to hide these things. Plus: you’re promoting your products to the wrong people. They don’t select the themes and plugins.
Similarly, if you have a plugin that requires a click to migrate or apply changes after an update — which does sometimes happen — that’s not just one click for a lot of us.
When I first wrote about some of these things three years ago, the common thread was the need for good UX and the related issue of managing user expectations.
Lately, though, it’s become about something else. I’m not here to talk about ethics because that’s not my area of expertise, but I will tell you a story. About six weeks ago I was looking — and not finding — the documentation for a certain plugin. I eventually found a post in which the developers were directing users to get it from their YouTube videos. In short, they were providing documentation in an inaccessible and non-searchable format to drive up their numbers. Unethical? It’s a gray area. But what’s certain is that it’s self-serving and inconsiderate of their users.
Advice for New WordPress Developers
New WordPress Developers
WordCamp Lancaster 2019
Who is this person
& why is she offering us advice?
• Security over all other things
• UI consistent with WP core
• Essential menus/submenus only
• Clearly-labeled fields
• Minimal admin notices
• No promotional popups
• Easy migration after updates
• Careful use of roles & caps