The Importance of “Why” Docs

Giving future engineers context on why decisions were made

Feb 11 · 4 min read
Photo by Emily Morter on Unsplash

Many of us have, at one time or another, blindly followed a pattern we noticed, thinking that must be the way to do it. We do so without questioning if that pattern is the best fit for our particular situation or if that pattern was ever a good idea to begin with.

In doing this, we rob ourselves of the opportunity to learn and deepen our understanding, to be intentional with our work, and, ultimately, to get better at our craft. Even more, we set yet another precedent for colleagues to do the same, instead of encouraging them to dig deeper.

The Girl and the Fish

I recently learned about the fable of a young girl watching her mother cook fish:

A little girl was watching her mother prepare a fish for dinner. Her mother cut the head and tail off the fish and then placed it into a baking pan.

The little girl asked her mother why she cut the head and tail off the fish.

Her mother thought for a while and then said, “I’ve always done it that way. That’s how grandma always did it.”

Not satisfied with the answer, the little girl went to visit her grandma to find out why she cut the head and tail off the fish before baking it. Grandma thought for a while and replied, “I don’t know. My mother always did it that way.”

So the little girl and the grandma went to visit great-grandma to find ask if she knew the answer. Great-grandma thought for a while and said, “Because my baking pan was too small to fit in the whole fish!”

via Ptex Group

The girl’s mother took off the head and tail of the fish because she was unaware of the great grandmother’s constraint of a small pan. She didn’t ask “why” when she adopted the recipe, and the great grandmother didn’t realize she should tell her. As a result, the girl’s mother was still able to cook fish, but she was cooking suboptimally. She was cooking uninformed.

By asking “why,” the little girl can change the recipe with confidence because she knows the original constraint of a small pan no longer holds.

Asking “Why” in Docs

Code tells you how a software system works. Docs tell you why a system works this way.

Code tells what, docs tell you why.” — Steve Konves at Hacker Noon

Writing down “why” as we build will:

  • Reduce the number of outages caused by changing code without understanding it
  • Reduce the time spent hunting down why software was written a certain way
  • Build a culture of craft and critical thinking in our teams
  • Empower our teams to build better

When to write “why”

Are there certain constraints that are impacting my work?

Is there anything I’m doing that requires explanation to understand fully?

These constraints can be related to:

  • Tight deadlines
  • Lacking resources on a project
  • Known bugs we’d like to mitigate
  • User-traffic patterns

Some building that requires explanation can be:

  • Why we decided to duplicate code instead of reuse code
  • Why we’re committing code in this order
  • Why we have this unusual-looking edge case handling

Write those constraints and explanations down.

Example constraints

  • We need to support backward compatibility of our iOS app to v1.1, so we have to pass this extra field
  • We’re expecting a 100x burst load tomorrow, so we’re increasing our base instance size
  • Team size is three engineers, so we only want to support one programming stack
  • Our project requirements aren’t clear enough, so we’re holding off on updating this feature for now

Example explanations

  • We’re avoiding our usual API for this because that API has been known to cause performance issues in use cases like ours
  • The special account balance value of -$200 indicates this is an employee account

How to Make “Why” Easy to Find

We’ll also go over how Bytebase makes sharing and finding the “why” behind your team’s work easy.

Better Programming

Advice for programmers.


Written by


This is the official blog of Bytebase — the byte-size knowledge base.

Better Programming

Advice for programmers.

More From Medium

More from Better Programming

More from Better Programming

More from Better Programming

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade