Using git to manage our playbook content

Three shapes from dxw brand balanced on each other

We were looking for the holy grail: ease of use by non-technical people while keeping the structural advantages of git

If you’ve worked with technologists, you’ve probably heard them talk about git or Github. git is the most popular way that software developers collaboratively work together on code.

When just a single character out of place could bring down an entire system, we have to put a lot of emphasis on making sure that every change we make is:

For a good non-technical overview of how git works then I recommend Alice Bartlett’s talk, Git for Humans. And for a story of how important it is for software developers to use git well, I recommend Tekin Süleyman’s talk, A Branch in Time.

Code is text, but it’s not the only important text that we write at dxw

We also believe it’s best to be open about who we are and the way we do things, so we make our playbook publicly available online. It contains a lot of important information for us, from how we manage projects to our ​​compassionate leave policy. Ideally, we’d like to be able to make sure that every change we make is easily shareable and reviewable before it’s deployed, and is tracked for future documentation. You may see where I’m going with this.

This is why, as a technology company, dxw has used git, hosted on GitHub, to manage changes to our playbook since 2015. This means that not only can you read our playbook, you can also see details about every one of the 1,617 changes that have been made to it in the 7 years since it was created.

The trouble with git

However not everyone at dxw can use git, plus applying several best practice techniques for software development, like having linters and pre-build scripts, made it even harder for non-technical people to directly contribute. As dxw has grown into an 80+ person multidisciplinary team, finding some time with a developer became a blocker for many to contribute to this important resource.

Our solution

After a round of simplifying and removing several years of technical debt, we started looking if it was possible to get the holy grail: ease of use by non-technical people, while keeping the underlying structural advantages of git.

We are not alone in this problem, and since we started our playbook, the ‘Jamstack pattern’ has become more widespread and standardised. The US government has even begun exploring similar ideas with its Federalist product.

We explored a few off-the-shelf products: CloudCannon, Forestry.io, and Siteleaf before settling on Netlify CMS. As always, we tested our assumptions with users, before switching over to our new process a month ago.

Since then we have had 5 non-technical team members, who had never made a GitHub pull request before, contribute changes to our live site by themselves. You can read how they did that on the guide in our playbook about contributing to the playbook (meta!). Even people outside of dxw can use this process to request a change, but only dxw staff members are able to approve any of those changes going to live.

Some outstanding issues

I think this mini-project has been a success, and the promise of managing important non-code content using git has legs. But we had to make some big compromises, and I’d like to share them honestly and publicly:

I’d encourage Netlify CMS and its competitors to try and solve these issues.