On Managing WordPress Development

I’ve used WordPress to run personal sites for almost ten years1. WordPress runs some of the library’s microsites2, but the development tasks were split between our graphic designers (HTML and CSS for child themes) and our web application developers (PHP, writing custom functions). In short: I never got to touch the code.

All of this changed with a couple recent projects. This time the application developers created WordPress instances, but all of the PHP, HTML and CSS development happened within my department. Design and implementation were handed off to our graphic designer with some pinch-hitting from me as needed. One site functions beautifully, while the other has been the bane of my existence for the last three months.

It isn’t anyone’s fault that things went dramatically sideways with one of the projects — these things happen. It’s a corporate cliché to suggest that this was a “learning experience”, but I did learn some things about managing website development among distributed teams, and how the process differs from working as a solo developer.

The Rules

  • Implement a content strategy for the website. Before writing a single line of code, take the time to gather and organize the content that will appear on the site. Create a sitemap and overview of all of the pages the site will contain.

  • Create a functional requirements document. This includes any plugins needed. For example, if your website requires a gallery, your requirements should state whether the site will use WordPress’ native gallery feature, or if you’ll require a third-party plugin. If you’ve never written a requirements document, here is a useful template.

  • Choose a simple yet robust theme or theme framework. Don’t choose a theme based on looks alone. Using your requirements document as a guide, research themes or theme frameworks, note whether required features are missing, and outline how you plan to incorporate any missing features (will you write custom functions, or is a plugin available?)

  • Develop locally, not on a live server. This should go without saying, but I mention because it emerged as an issue during implementation. Having a sandbox server environment that mirrors the live sever configuration is essential, and it reduces the amount of time you’ll spend moving the site from the staging server to a live site. I prefer MAMP for local WordPress development3, but the Bitnami WordPress Stack is also a good choice (and somewhat easier to set up than MAMP).

  • Use WP_DEBUG to test your code. Debugging code is an important part of any project. Use WP_DEBUG on your staging server to trigger the debug mode in WordPress and to ensure compatibility.

  • Outline your functions before writing the code. One of the best rules I learned as a novice developer was “Code tells you how, but comments tell you why.” Ideally code should be clean enough to be human-readable. Some developers think that commenting makes for cluttered code, but when you’re working with distributed teams, comments (and meaningful function names) ensure that everyone understands a function’s intended purpose. The image below shows how I map out functions using comments before writing code:

an image that shows how I map out functions with comments

As a manager, my job is to support my team as much as possible. I believe in empowering people to make their own decisions, and having structured yet flexible processes in place is an essential part of the process, and is one of the most important tasks for a manager. I’m still learning; hopefully you’ll benefit from some of my more painful lessons.


  1. Not this version. This site is generated by Jekyll
  2. Small scale websites that exist as subdirectories or subdomains of the library’s primary domain. 
  3. This is a case of do as I say, not as I do. The setup at work is different (and outside of my control), but if the choice were up to me, this is how we would approach local site development.