The Importance of “Why” Docs

Giving future engineers context on why decisions were made

Feb 11, 2020 · 4 min read
Image for post
Image for post
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

Image for post
Image for post

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

Like the little girl, we want to break the cycle of doing without understanding. We can break this cycle by asking “why,” and by documenting why as we build.

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”

As you code, throughout the day, ask yourself:

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

  • This feature needs to be released immediately, so we’re accepting poorer code quality
  • 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 duplicating our blog model because we want to move to a backward-incompatible model
  • 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

Part 2 of this post will cover how you can use Git to capture the “why” related to your code as part of your daily routine.

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

Better Programming

Advice for programmers.

Sign up for The Best of Better Programming

By Better Programming

A weekly newsletter sent every Friday with the best articles we published that week. Code tutorials, advice, career opportunities, and more! Take a look

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.


Written by


This is the official blog of— the fastest way to write, organize, and collaborate on notes.

Better Programming

Advice for programmers.


Written by


This is the official blog of— the fastest way to write, organize, and collaborate on notes.

Better Programming

Advice for programmers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app