Our new team practices site, and the democratic repository behind it

A month ago, we published our web and design team practices website, from the repository that we’ve been building up for nearly two years now.

I’ll try to explain why I am so proud of it.

Why practices?

A strong team needs agreed standards and principles, to help anchor discussions and illuminate common goals.

When the UK Government Digital Service (GDS) overcame a sluggish, bureaucratic civil service to create gov.uk, their exemplary design principles played a central role in getting everyone on the same page.

1. Start with user needs
2. Do less
3. Design with data
4. Do the hard work to make it simple
…

Government design principles

Principles like this, shared by the whole team, are immeasurably useful in many ways:

• Team members have a shared understanding of the team’s cultural values, and can rely on those values
• New team members can get up-to-speed on the team’s approach to problems quickly
• Long discussions can be curtailed by linking to the agreed standard
• The best principles offer a beacon to keep work and discussions on track, focused on the right things
• It’s easier for team members who work remotely (we have quite a few) to stay connected to the evolving team culture

For a few years now, we’ve been experimenting with different ways to create some shared practices and principles.

Why a repository?

GDS’s principles implore us to “do the hard work to make it simple“, and certainly the amount of thought and discussion that went into these simple, concise statements must have been immense.

It might seem like a simple thing to write down a list of principles. But it turns out, getting a whole team to agree on a single set of statements is a very difficult task, especially with a team as enthusiastically opinionated as ours.

We’ve tried many times to create our team’s common standards and principles – we’ve had long email discussions, small meetings and large interactive whole-team planning days. But we never quite managed to agree – there was always a nuance we hadn’t quite met, or an opinion not accounted for.

As we clearly weren’t going to get to a complete set of principles from any single effort, we decided that it would make more sense to just start somewhere and gradually build from there.

And so, in January of 2016, we decided to create a bare-bones repository as the starting point for our standards, to be built up bit-by-bit. In April we added our first document, “BEM coding standard”.

Working slowly

This repository allowed us to work slowly, making contributions as we found time. It wasn’t until February 2017 that we started our contributing guidelines, adding rules for approval in March:

Approving a pull request

Before a pull request is approved and merged:

• A reasonable effort should be made to bring it to the attention of the whole team
• It should also have been :+1:d by at least 2 team members
• It should have been open for at least 24 hours

Once it is merged, it should be brought up in the next relevant team meeting to ensure the whole team is aware of the change.

These rules are to reinforce the idea of working slowly. Much more than speed, it is important that changes are carefully considered and agreed by everyone.

• New changes can be suggested by anyone as public pull requests, or ideas can be discussed in issues – nothing is set in stone
• We ask all team members to “watch” the repository, so they will get notified of any new activity
• Pull requests can be discussed over many days or weeks, with no pressure to reach a conclusion prematurely
• We highlight open pull requests in our morning stand-ups, and often discuss them in meetings
• Once consensus is achieved by all people who commented on the pull request, it is merged

This way of working also fits in much better with our distributed team. Our team members work in many different time zones – from the UK to the USA, Poland to Australia. By working slowly and through pull requests, the whole team can effectively collaborate without the need to have discussions in real time.

Democratic chaos

Now, 2 years after its inception, we have 26 documents in our practices, and plans for many more. Despite our slow review process, our practices are somewhat sprawling and messy – certainly much messier than I had envisaged in something like the polished GDS principles (I hope to provide a little more consistency in the future). At the same time there’s still a huge amount of team shared knowledge that’s missing from the practices.

And yet, we’ve certainly reaped the benefits. The exercise of working through the pull-request process often helps build a team consensus which is then very helpful going forward. The ability to simply provide a link to someone to explain the team’s position on an issue is sublime. The team has also grown recently, and the practices helped a lot with the on-boarding process.

Above all, I believe we can truly say that the practices represent the position of the team. There is no elite group or thought leader handing down principles from on-high – these practices genuinely represent team consensus. Such consensus is often very hard to achieve, and I believe its value cannot be overstated.