Using git to manage our playbook content
We were looking for the holy grail: ease of use by non-technical people while keeping the structural advantages of git
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:
- easily shareable and reviewable before it’s deployed
- tracked for future documentation
- revertible if something goes wrong
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.
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:
- The Netlify CMS user interface, while simple, was not intuitive to our users, and our guide to using it was essential
- Pull requests are generated in the background, with no indication to the user that they have been created, or how to find them. We have a Slack integration to try and fix this, but users can still need hand holding at this step
- There’s no option for users to write their own commit messages. Every change now has a commit message of ‘Update Index’, which is not very informative!
- We would prefer the new beta feature ‘Open Authoring’, which we use, to create forks for every user. Having users with repo write access still create branches created a dual editing workflow
I’d encourage Netlify CMS and its competitors to try and solve these issues.