Chesterton Fence and Documenting Decisions

Document current decisions so that future developers make better decisions.

Photo by Henry & Co. on Unsplash

Chicken’s Fence

Imagine you buy a house with a two-meter fence around the backyard to keep chickens inside. You think that the fence is too high. The chickens can’t fly, and there is an excellent view outside of the garden. Therefore, you reduce the fence to half a meter.

That night, foxes come and steal half of your chickens. The fence was two meters to prevent foxes from coming in, not to guard the chickens from escaping.

This fence is a funny example of Chesterton’s Fence.

“Chesterton’s Fence is a principle that says change should not be made until the reasoning behind the current state of affairs is understood. It says the rash move, upon coming across a fence, would be to tear it down without understanding why it was put up.” Thoughtbot

Imagine that the owner kept a log of the decisions; then, you’d know the fence was for the foxes. After a few months, the foxes disappear from the area due to climate change. Then, you can safely remove the wall.

No fox comes in that night.

What and How versus Why

When you saw the fence, you assessed the material and how it was attached to the ground. But you didn’t know why the fence was two meters high.

To understand whether you could change the fence, you needed to understand why it was set so high. Knowing the what and the how is different from knowing the why.

Software Engineering

Software projects are full of Chesterton’s Fences.

Software projects are full of features, functionality, and patterns that seem silly, unnecessary, or overengineered at first glance. Yet, if we remove those features, we might get into trouble. We might lose half of our chickens.

Searchable Discussions

To help the future team (or ourselves in a year), we need to explain why some features are the way they are.

The easiest way to help the future team is to have discussions in writing. The written word is easily searchable, except for chats: chats are written communication but not easily searchable.

“If a discussion will matter after today, don't have it in a chat room.” Mike Crittenden

Written Discussions

We don’t need grandiloquent documents with status, pages of research, and pros and cons lists that need to be signed off. It’s enough that the record covers one decision and has structure enough so that people understand the context.

Writing the discussions doesn’t mean avoiding meetings. Meetings are great for solidifying the outcome. Moreover, if the document already exists, it’s easy to summarize the result after the meeting.

Use Async Meetings to keep a decision log. The future team will appreciate it.

Document current decisions so that future developers (or our future selves) make better decisions.

---

Thanks to Michal and Yusef for reviewing this article 🙏