Chesterton’s Fence and tech documentation

What’s Chesterton’s Fence?

Chesterton’s Fence is a concept in public policy that states:

The principle that reforms should not be made until the reasoning behind the existing state of affairs is understood.

I ran into it for the first time a while back and it immediately took my thoughts to documentation of software projects.

An article at Sprouts defines it in more layman’s terms as

Chesterton’s Fence is a simple rule of thumb that suggests that you should never destroy a fence, change a rule, or do away with a tradition until you understand why it’s there in the first place. The principle assumes that fences have a purpose, were carefully planned, and cost time and money to erect. Someone must have had a reason for thinking that a fence would be a good idea. So what if we just take them down?

Before I knew about this named concept, I used to use a “pizza in office fridge” example:

Imagine you come to the office one morning and see a few pizza slices in an unmarked container. You could eat them (especially if it’s common to have leftovers from events), throw them to bio bin or ignore them. But since they are unmarked, you can’t know when they were put there (are they still edible?), do they belong to someone or are they up for grabs and what kind of pizzas they are. So unless more instructions follow, the safest bet is to ignore them. This can lead to the fridge being full of pizzas someone meant for their colleagues to eat but without instructions, nobody knows what to do.

What does this has to do with documentation?

I have been to various projects where the lack of documentation caused an issue where nobody in the team remembered or knew why something, initially weird looking, was implemented the way it was.

Even a bit of documentation would have helped so much: if we knew why it was originally done that way, we could have considered if situation had changed and if it was safe to remove or change.

In my talk Contemporary Documentation, I’ve talked to developers about how and why to document decisions when they are being made, and stored in a format (in this case, version control) that doesn’t erase the old decisions as software evolves.

In an optimal case, we’d have full test coverage (in terms of use cases, not necessarily code lines executed) but that’s kind of a pipe dream in most software projects. With a perfect coverage, we could more confidently remove things and see if anything breaks and adjust accordingly.

But with imperfect one, we are left with a difficult consideration: do we take the risk of breaking the fence which can lead to bigger, unexpected problems down the road or do we ignore it, being on the safer side but maybe slowing us down with new features or inefficiencies in the software.

Keeping the fence in mind when you write software and its documentation, especially internal one, can save you a lot of headache in the future.