We do a good job of evangelizing the different tools, environments, and ways to tackle problems in our space (that is, within WordPress development), but I often wonder how well we do for actually documenting our practices, procedures, and so on for others.
Sure, some companies open source their practices, and that’s great, but does every company? And should they?
Sometimes, I think people believe that if a company bases itself on open source, then they should have everything out in the open:
- Their software,
- Their practices,
- Their financials,
- And so on.
I don’t agree, but I do think there’s something to be said for documenting your practices within your team as this benefits both you, your teammates, and people you may end up bringing on to a project or on to your team for future work.
Document Your Practices
What does this mean, exactly? It’s hard to say because each company is different.
But I do know that since Eric and I started working on Pressware Plugins, one of the best things that we’ve done for ourselves and our sanity is to compile a list of our practices and procedures so that we’re able to stay on the same page concerning the work we’re doing.
For example, outside of our preferred project management solution, we have a wiki in which we attempt to stick to this purpose:
This wiki is used to document all information for our development, staging, and production environments. It links to all supporting documents and should be the first place to look when any questions about our environments and tertiary services are raised.
No, I don’t think every set of documentation needs a goal, but I do believe that having one helps guide decisions on what to include and what to ignore.
I digress on this for now, though.
How It Looks
So what about our documentation?
- It’s private. This isn’t something that anyone else but us needs to access because the practices, procedures, and other information is relevant only to us. It provides exactly zero benefit to anyone else but us.
- It’s being refined. Software regularly undergoes development, and some of our practices do, too. This doesn’t mean that the basics change. That is, we still have three environments and a deployment process. But what happens after the deployment process via web hooks or something similar may change as we get deeper into the weeds.
- It’s organized. It’s not a single massive document. It’s a collection of seven to 10 documents all of which have a single point to them. If you need to know how to configure Nginx for a new server, there’s a page for that. If you need to know which environment is for plugins and which is for the storefront, there’s a page for that.
And what’s contained within the wiki? Again, this will be different for each team. Some of the information that we keep includes:
- How to set up, configure, and prepare a local development environment so you can get to work quickly.
- An explanation of our staging environments so you know what goes where.
- Instructions for dealing with the production environment (and why not everyone who may be involved in a project will have keys to that particular aspect of the business).
- A template for server configuration
- How to work with SSL certificates for each server.
- Information and procedures for a help desk, social media accounts, and version control.
- A primer for working with Git just in case, the person, is brand new to it.
But that’s just us. And notice, I don’t share where we keep this information because it doesn’t matter as long as it’s safe and it’s accessible via your team.
The Where is Secondary
Sometimes, developers get so caught up how we can manage their information we forget actually to manage said information.
I do think you should absolutely document your practices and procedures especially if you’re going to be bringing people on to your team even if it’s just for a project or even if it’s just for your own reference.
When Pressware was contracted to work with Reaktiv Studios on a project last year, they had all of the necessary information about their practices documented, and it made getting involved and up-to-speed very easy.
They are an example of how to do it right.
Finally, I don’t have advice on what you should use because that’s secondary to doing it. If using an internal document in Basecamp works, then do that. If using a wiki in GitHub works, that’s fine, too. If you want to keep something stored in Dropbox or iCloud, then go for it.
Again, document your practices but remember that the where is secondary to the how.