The 3 Whys of Software Documentation

TL;DR: After 20+ customer interviews, the pattern is clear: the most valuable piece of documentation is the "why" behind decisions. I've identified three types of "whys" in software and have created a practical framework for capturing each one.

The Most Important Thing to Document

Over the past six weeks, I've interviewed more than 20 software engineers, engineering managers, and technical leads. Every single person complained about the same thing: finding why the code was the way it was.

Why a particular architecture was chosen. Why a feature was built one way instead of another. Why a seemingly odd implementation detail exists. Finding the "why" behind the code unlocks understanding and leads to greater velocity and quality.

Not the "what." Not the "how." The "why."

The "What" and "How" Are Already Covered

Don't get me wrong, the "what" and "how" still matter. But they're the easiest to figure out. You can usually answer what code does and how it works just by reading it. Clean code practices make this even easier. Moreover, modern AI tools are remarkably good at exploring a codebase and explaining what a given piece of code does and how it works.

But ask an AI assistant why your team chose a 3-second timeout instead of a 5-second one and you'll get a hallucinated guess at best. That context lives in the heads of the people who made the decision, and nowhere else.

Why the "Why" Matters

The "why" behind your code gives critical insight into three things that no amount of code reading can reveal:

• Business decisions and constraints: Why did we build feature X instead of feature Y? What trade-offs were made and what drove them?
• Established technical best practices: Why do we follow this pattern? What went wrong when we did it differently?
• Tribal domain knowledge: Why do we handle this edge case? What do we know about our industry or product that isn't obvious from the code?

When this context is missing, engineers are left guessing. They either spend hours tracking down the one person who might remember or, worse, they undo a deliberate decision because they didn't know it was deliberate.

The 3 Whys

During my time as a software engineer and throughout these interviews, I've noticed that not all "whys" are created equal. They vary in scope, impact, and how they should be captured. I've started calling this framework the 3 Whys of Software.

Knowing that you need to capture the "why" is only half the battle. The other half is figuring out how to capture it without slowing your team down. The key is matching your approach to the type of "why" you're dealing with.

1. The Big Why

These are large, impactful business and technical decisions. They shape the direction of teams, projects, and even entire companies. Some examples are:

• Why are we moving from Python to Java for new services?
• Why did we build feature X instead of feature Y?
• Why do we care about this event or metric?

Big Whys tend to have knock-on effects across teams. They're the decisions people reference months or years later when someone asks, "Wait, why do we do it this way?"

How to capture: Before the code

Big Whys should be captured before any code is written, via a proposal document. Proposal documents include things like design docs, requests for comments (RFCs), architectural decision records (ADRs) and even project requirement documents (PRDs). These are the right vehicle because Big Whys tend to require consensus across teams and have lasting effects on how the codebase evolves.

When to capture: If it's a major change to day-to-day operations or requires buy-in from multiple people, write it down first.

For example, if your team is migrating from Python to Java for new microservices in a large, existing codebase, you almost certainly want to capture the rationale, concerns, trade-offs, and planning details in a proposal. On the other hand, if you're starting a brand-new company and picking a language for the first time, the rationale behind "Python vs. Java" probably isn't worth a long formal document. Instead, jot down a quick note in the project readme (e.g., "written in Python by Python experts").

2. The Little Why

These are implementation-level decisions. They're smaller in scope but come up constantly in day-to-day development. Some examples are:

• Why do we have a 3-second timeout instead of a 5-second one?
• Why do we use HTTP client X instead of client Y?
• Why is this method public instead of private?

Little Whys are the decisions that trip people up during code reviews and debugging sessions. They're easy to lose because they often feel too small to document at the time.

How to capture: As you go

Little Whys should be captured as part of or immediately after making changes. As a general rule, if you find yourself talking about specific lines of code in a Slack thread, you're probably talking about a "little why" that should be documented.

The good news is that most teams already have mechanisms for this, they just aren't using them intentionally:

• Code comments explaining why, not what. "We use a 3s timeout because the downstream service SLA is 2.5s" is infinitely more useful than "// set timeout."
• Pull request descriptions that explain the reasoning behind implementation choices.
• Review comments that capture the back-and-forth that led to a final decision.
• Clean code practices that make the "what" self-evident, freeing up comments for the "why."

The trick is to make capturing Little Whys a natural part of your workflow rather than a separate chore. If your team already does code reviews, you're halfway there.

3. The Weird Why

These are the hyper-specific pieces of domain knowledge that only make sense to people working on a particular project, team, or industry. They're the things you learn the hard way. Examples:

• Why do we treat our integration with third-party A differently than third-party B?
• Why do we consider these attributes personally identifiable information (PII) but not those ones?
• Why does this workflow have an extra approval step only for customers in this region?

Weird Whys are probably the most dangerous to lose. They represent the kind of knowledge that lives in a single person's head and walks out the door when that person leaves. If you've ever heard someone say, "Oh, you have to talk to Sarah about that, she's the only one who knows," you've encountered a Weird Why.

How to capture: When they come up

Weird Whys are unpredictable by nature. You can't plan for them. But you can capture them the moment they surface. Here's a simple rule: if there's a question that only a member of your team could answer, write that answer down.

Weird Whys can live in a lot of places:

• FAQ docs for the team or project
• Code comments next to the peculiar logic they explain
• Embedded within Big Why proposals, especially when building something that requires domain expertise

The best place for a Weird Why is wherever your team will actually find it. Create processes around capturing these whys that works for your team and stick to them.

Start With One

You don't need to overhaul your documentation practices overnight. Start by capturing one "why" this week. The next time you make a decision, no matter how small, ask yourself: "Would someone new to this codebase understand why I did this?" If the answer is no, leave a breadcrumb.

At DocuCodes, we're building tools to make capturing and sharing the "why" behind your code as natural as writing the code itself. Our upcoming Proposals feature will make capturing Big Whys easier than ever. If you're tired of losing context every time someone switches teams or a Slack thread disappears into the void, check us out.