Take Control

Writing down your policies or processes isn't exactly thrilling, but it's a step in the right direction.

Unfortunately, it's far from the last step.

Documenting all your bits and pieces stops you from relying entirely on tribal knowledge, which has a tendency to constantly mutate like some sort of perpetual game of Chinese Whispers.

That's not to say that written documentation doesn't mutate though.

Did You Hear That?

One of the most common challenges with written documentation is change management.

Your written documentation is intended to be the source of truth, especially when it comes to things like policies and processes. People should be able to read those words and glean an appropriate amount of understanding.

But change is inevitable.

Things mutate and shift over time, processes evolve and adapt, and policies need to be updated if they are to remain relevant.

The worse case scenario is simply letting the documentation rot, where it grows increasingly less representative of reality over time. The ramifications of this range from the obvious (misunderstandings and mistakes) to the subtle (a growing cultural distrust of documentation in general).

A better scenario is if the documentation is updated so that it mostly represents reality. In a lot of places, this tends to happen in an ad-hoc fashion, being done by whoever is most motivated to do so. Maybe there is even a person dedicated to the task.

But it's not the best case scenario.

The best case scenario is if the documentation is updated in lockstep with policy and process change, and said updates are done in such a way that people are aware of what is changing and why.

The Pyramid Spoke To Me

Last year when I was interviewing at Gitlab I learned about their handbook.

This publicly visible document describes, in great detail, how Gitlab operates. It contains everything; mission, vision, policies, processes, teams and as far as I can tell, probably more than one reference to a kitchen sink.

It is glorious.

Most companies have an equivalent. Maybe not quite as well structured or managed, but still, something that fulfils the same need. Atlassian has a big old Confluence instance for example.

But what Gitlab does differently is change management.

Changes to the handbook are done via merge request, which is basically the same way that code changes are managed in software development teams.

If someone wants to change the handbook they make the change on a local copy of it, then create a request to merge that change into the master copy. When they do so, I imagine they also provide some sort of context as to why they are making the change.

Whoever is responsible for maintaining the section of the documentation being changed then reviews the proposal, makes comments, and accepts or rejects the change.

Not only does this provide a structured mechanism around change management, it also provides a way to communicate those changes. Sending the merge request to the people affected by the change is an easy way of helping them to understand the change that is being made and why.

Here is an example that I pulled from the Gitlab handbook a few seconds ago, about an update to the team listing. I don't know what the team listing actually represents, but it's clear what is being changed and why.

That's pretty awesome.

It Was Just Noise, But I Understood

I don't know when the Gitlab handbook sprung into existence, but I have to imagine that it was around the time the company started.

I say this because I can't begin to imagine how you would retrofit something like peer reviewed policy and process documentation into an organisation that already has a significant body of written work elsewhere.

I suppose you could create a new documentation repository that followed the desired pattern and then incrementally move things over, but that sort of fundamental and foundational change seems like it would require a monstrous amount of effort and discipline over a long period.

Not only that, but you couldn't stop halfway through. You have to run it through to end, or people will just continue to use the old documentation repository because it's easier. Or, more likely, they would get confused as to which one to go to and just ask someone instead.

And the repository itself is key, because you need something that will support the concept of merge requests as a first-class citizen. You could try to achieve the same thing with a mandated process and extreme discipline, but you would probably fail.

If you narrow your scope, it might be easier though. Trying something like merge requests for team level documentation would be a far smaller problem, requiring buy-in from less people.

In fact, if you focus on just documentation that is intended to be read (i.e. reference documentation, like runbooks, policies, processes, etc) as opposed to exploratory documentation, you narrow your scope further, making things even easier.

Still, considering how pervasive something like merge requests would be, I just don't see any easy way to try it out and see if it's actually a good idea in practice.

Which makes me sad.

Wait, Is This Gun Alive?

I think the idea of controlling documentation content via merge requests is an interesting one, and I'd love to give it a go some day.

But I think it would be one of those tricksy ideas that requires a lot of buy-in and participation before it really shines. Like building a new platform or service that requires more and more people to use it before it is actually useful to all of the participants.

For now, I'll just keep the idea sitting in the back of my head until the next time I have to set up some sort of documentation from scratch.

Who knows, maybe I'll join or create a company that has nothing at all.

Which might be sooner than I think depending on how the management changes at Atlassian shake out.