As demand increases on a business, there comes a time when you look at expanding and taking on more members. The problem is, especially for small 1-3 person teams, that most of the agreed best practices are in peoples heads.
How are you meant to inform a new member how the team works if it's not documented anywhere? Believe me, helping new additions adapt faster to the working habits of the company is a massive bonus and a boost in productivity.
It's safe to say that Nymble has hit this stage recently and that has created the need for us to finally write down our best practices for developers.
Over the past week, I've been sat at my desk planning and documenting all the main beliefs and ideals of Nymble's development team and what keeps our work up there with the best.
Planning the Document
Figuring out the structure and format of the document was our first task and deciding on the format was actually one of the easiest decisions. Being a forward-thinking digital company, with remote workers, it only made sense to build a wiki-style site that we could send out to everyone as they join. It also meant that current team members could refer back to it at any point.
We ended up deciding on the following structure:
In this section, we give some information about the document such as who it's aimed at, as well as its goal.
Here we briefly describe the tools that would be needed for new team members. We cover things such as IDEs and text editors, local environment and command line tools that will be needed to work smoothly within the Nymble team.
As our business mainly works within PHP, it's only right we lay out our PHP best practices.
This section is split into a couple of sub-sections.
Here we discuss code style and our thoughts on controller structures when working outside of WordPress. Things such as talking about our use of the Hexagonal Rails Architecture
In this section, we inform the reader about our guidelines for WordPress development. Whilst we mostly follow the official WordPress guidelines for PHP development there are a few deviations that make debugging smoother and readability easier.
As we work a lot with WordPress themes, we thought it was best if we wrote about our basic starter theme, it's requirements and installation as well as any plugins we use on a regular basis.
We give our theme structure and what each directory should do in order for people to be able to pick up our themes with little hassle.
We have discussed our best practices when writing CSS/SCSS in this section. From our philosophy around CSS right down to our structure, naming conventions, and rules around nesting.
Semantic markup makes a site what it is, so this is what we wrote about in this section. Why we write markup like we do and how people should continue doing it.
Standardising this makes everyone's life easier!
Why, when and how we automate testing using Behat and PHPUnit.
Our Git methodology
Writing the Sections
So now we'd planned the sections and agreed on a format for the document it was time to start actually fleshing it out. This was pretty easy as we'd already decided a lot of what needed to be said during the planning stage. It was simply a case of sitting down and getting it written.
In our case, Markdown seemed like the best option for writing. Not only is it easy to read and format for the author but we could use a generator like Hugo to compile it into a static website as we'd agreed, so this was the route we took.
Why Release It?
This was a simple decision for us. We'd just documented how new and current team members should work in order for us to write our best code and build the best projects we can, why wouldn't we then release that to the world?
We believe in our development processes and are confident that they work, after all, they enable us to put out the work we do. We want others to see how we work, documenting our process allows others to scrutinise them. Not only can they then look at their own internal processes and make changes if they need to, but they can also talk to us about ours.
The development ecosystem is ever-changing and we always want to be at the front of the pack. Only through collaboration can we keep learning and evolving.
We now have a near complete handbook of our working practices to give to new team members in order to help bring them into the team and keep Nymble working at its ever high standard.
Feel free to go and take a look at the handbook at https://engineering.wearenymble.co.uk and let us know what you think.
Are there any changes you'd make? Have you documented your processes and if so how did you find the task?