These days everyone is talking about following best practices, established standards, and just doing it right. This is undeniably great, but does your company have a clear definition of what any of this means? I ask because documenting this information can create a valuable resource for your employees and contractors to learn from—all while establishing a company-wide standard.
More importantly, however, it creates a way to offer the most constructive type of feedback to those who are not doing it right. Instead of telling them they are flat out wrong, you can direct them to where it says how to do it right.
Establishing best practices for a WordPress development agency (of any kind) can also be part of creating standard operating procedures (SOP). Having an established set of SOPs not only creates consistency and helps to further refine expectations, but it also eases the on-boarding process of new employees, as your institutional memory is recorded.
Like programming, there is no reason to reinvent the wheel—your best practices can be linked to documents. In this article, I will discuss where to find the best documents to help construct your best practices, what they should include, and what standard operating procedures to use. I will also discuss the best way to store this document.
Do you really need this?
Let’s answer the most obvious question before we get started: Do you really need this? The answer is yes. In some form or another, you do, no matter who you are. You might not need to go all out and do everything I recommend in this article, but defining your best practices and establishing a workflow will definitely save you time (and frustration) in the future.
For example, one of my jobs is working for the Pods Foundation, where we use a Git workflow adapted from the standard “Git Flow” strategy. We expect our contributors to follow it, or we will not accept a pull request. In our GitHub repository we have a document explaining how it works.
Sometimes a few readme files are all you need, but just remember the point here is to spend a little bit of time now to save time, money, and sanity in the future. In other words, don’t be short-sighted in investing time now to see gains later.
Remember to be flexible
It’s important to keep in mind that following policy for the sake of policy takes the joy out of work in a way that is destructive to productivity. So does following a policy that makes no sense. It is therefore important to let these practices and procedures evolve over time.
Once you have your best practices and SOPs in place you should make following them a requirement for all employees and contractors, but you should also invite dissent and experimentation. Don’t be afraid to try new things, and, if they work, document them and make them a part of your workflow.
Before you do, however, be sure to ensure that you are changing what you do because the result will be better and save time. Curtis McHale wrote a great article on the danger of change for the sake of change, which I strongly recommend reviewing.
Everyday, my twitter and Facebook feeds are filled with links to shiny new tools that I’m often tempted to use. But if something works, is it worth spending hours of valuable time learning something new that does the same thing?
Automate as much as you can
Writing down the steps for your standard operating procedures is important. It makes it easier for people to understand the correct way to do things, but it also adds uniformity to repetitive work.
One good thing about defining your SOPs is that it’s a good first step in automating as many tasks as possible. I believe that we need to be firm in the division of labor between humans and machines, meaning that both should stick to what they are good at. Machines do repetitive, predictable tasks very well, while humans are good at creative work.
This is why I am so fanatical about automating as much of the development process as possible. I have written about dependency management and task automation a lot over the last few months on Torque. All of those articles arose out of my own efforts to automate as much of the repetitive parts of my own work as possible. I’m very happy about how it has helped, and I take comfort in knowing that when I fix one mistake in an automated system, it will be fixed everywhere.
Where to write your best practices
While I would love to suggest a WordPress-based solution for this, I don’t think it is the best option when compared to a wiki. You could create a WordPress site for this, but since your best practices and standard operating procedures are going to result in discussion on how to improve them, a wiki simply makes more sense.
Wikis are more editable, and if you use a GitHub or Bitbucket for your wiki, you get built-in version control and issue tracking. Having issue tracking and version control makes it easy to discuss potential changes, and even create proposed changes in pull requests for anyone to control.
Both GitHub and Bitbucket’s wikis do not give you much in the way of customization of the design of the site, but they look fine. You can always use one of the many tools out there to create static HTML sites from GitHub repos—but unless you have a real need, or doing so is part of your marketing strategy, why bother?
What to include
What kind of work your company does is really going to make a big difference in what best practices and SOPs you need to define. If you make client sites, for example, you will need SOPs for creating local and production environments, and learning how to move between them. If you are a plugin or theme developer, you will need SOPs for defining how you structure your plugins or themes and how you test them.
I have worked on SOPs for my own company, as well as for clients, and they have taken the form of anything from a few how-tos, to step-by-step instructions for setting up a project from local development to deployment. The good thing about creating SOPs is that it provides an opportunity to “level up” your workflow. Documenting a bad workflow is pointless. So use documenting it as an opportunity to invest in doing it right.
No matter what type of work you do, you need to have best coding practices, even if you do not write a line of code. This is especially true if you do not write code, because you are fully relying on other people’s code, and therefore need a metric for evaluating it in your quality control stage, as well as when deciding on which plugins and themes to use.
This is one of the parts of the document that can be mainly links, with highlights. For example, for the WordPress plugin and training company I run, CalderaWP, we define our coding best practices almost entirely in links to the WordPress.org handbooks, 10up Engineering Best Practices, and WordPress VIP’s best practices.
These standards can overlap and become contradictory, which will require further definition on which ones you follow. For example, as I’ve stated several times in recent articles, I don’t think that the WordPress core development standards for class naming make sense outside of core—I think that a PSR-4 standard makes much more sense.
Another element of this documentation I strongly recommend that you include is a standard for defining naming conventions in a project. Using unique function prefixes, class namespaces, and following a project’s branding is important. A standard for documenting these things in each project is a fundamental step in ensuring that these important elements are consistently followed.
Don’t forget to have fun and practice forgiveness
The point of all of this is to invest time now to save time in the future. If this effort isn’t leading to that result, then it needs to be reevaluated. Also keep in mind that throwing a ton of procedures and policies at people and expecting them to follow them to the T is simply unreasonable. Be forgiving. In fact, that’s one of the benefits of doing this: It helps ensure that correcting someone is a teachable moment, either where they see exactly how they could have done better or they show you where your established best practices could be improved.
What we do when we make stuff with WordPress is a lot of fun and it should continue to be that way. Defining and implementing standards and practices should be a process that helps people get the dull parts of their day out of the way quickly, and consequently have more fun being creative. When you’re flexible and forgiving (and automate as much of the repetitive parts as possible) that is possible.