Stop Telling Me What the Code Does. Tell Me Why I Should Care.

I’ve been reading tech articles for twenty years, and I’ve hit a wall. I can’t stomach another 2,000-word piece that meticulously catalogs every parameter of a JavaScript method, lists all the accepted data types, and then slaps on a code block copied directly from MDN. That isn’t an article. It’s a reference page with delusions of grandeur. It tells me what. It never, ever touches why.

This problem is everywhere. It infects company engineering blogs, personal dev diaries, and the big tutorial mills that dominate search results. You search for “how to use React’s useMemo” and you get ten pages that all say the same thing: “useMemo accepts a function and a dependency array. It returns a memoized value.” Thanks. I can read the docs. What I can’t read in the docs is the mental model I need to stop wrapping every single variable in my component with useMemo and creating an unreadable disaster. The docs won’t tell me that I’m probably solving a problem I don’t actually have. A good article would.

The Hollow Shell of a “What” Article

Let’s dissect the typical offender. It usually starts with a friendly, generic introduction: “State management is a core concept in modern frontend applications.” No argument there, but it’s also a sentence with zero informational content. Then we move to the installation command: npm install some-library. Groundbreaking. Then we get a block of code, maybe 30 lines, with inline comments that just translate the syntax into English. // this maps over the array sits right above .map(). I can see that. My eyes work.

This format treats the reader like a compiler. It assumes my only job is to ingest syntax and spit out a working application. It ignores the fact that I am a human being trying to build a mental map of a system. I need to know about the trade-offs. I need to know when this tool was the wrong choice for the author and they had to rip it out at 2 a.m. That’s the stuff that sticks. That’s the stuff that saves me from making the same mistake.

The worst part is that these articles aren’t technically wrong. The code runs. The method signature is accurate. The output matches the description. But the entire piece is a pedagogical dead end. It equips me to solve the exact, contrived example on the page and nothing else. As soon as I hit the messy real world, with its legacy constraints and weird business logic, the knowledge vaporizes. I’m left with a snippet I can’t adapt because I never understood the principles underpinning it.

Code as an Argument, Not a Decoration

Kai Lindström doesn’t write code examples to show you the syntax. I write code examples to prove a point. There’s a fundamental difference. If I’m arguing that a particular pattern leads to untestable spaghetti, I’m not going to show you a pristine, happy-path implementation. I’m going to show you the ugly version first. I’m going to let you feel the pain of trying to mock that deeply nested dependency. Then I’ll show you the refactored version, and the contrast will be the argument itself.

Let’s take a concrete example from the endless debate on “composition vs. inheritance” in object-oriented design. A “what” article will define both terms, show you a class that extends another class, and then show you a class that holds an instance of another class. It concludes, blandly, that both are valid tools. A why article would start with a real bug. Imagine a Robot base class with a walk() method. You subclass it into a BipedalRobot. Fine. Then you subclass it into a QuadrupedalRobot. Still fine. Then the product owner asks for a SnakeRobot that doesn’t walk at all but inherits all the battery management logic. Now you’re stuck. You either override walk() to throw an exception, violating the Liskov substitution principle, or you refactor. The why article uses that exact code dead-end to argue that inheritance models an “is-a” hierarchy that breaks the moment the real world gets messy. The code is the evidence, not the filler.

The Performance Trap and the “Why” of Measurement

Another domain poisoned by the “what” philosophy is performance optimization. You’ll find a thousand articles that say, “use string concatenation instead of StringBuilder for small strings” or “always use a hash map for lookups.” These are presented as immutable laws handed down from the mountain. They are not laws. They are context-dependent heuristics, and parroting them without the “why” creates cargo-cult programmers.

I once saw a junior developer tie himself in knots trying to avoid a StringBuilder in a C# application because an article told him the overhead wasn’t worth it for a few concatenations. He was building a logging framework that would process millions of messages. The “small string” assumption in the article was completely invalid for his context, but the article never explained how to make that judgment. It never walked through a benchmark. It never showed the disassembled code to explain the allocation cost. It just gave a rule. A proper why article would have put a profiler on it. It would have shown the memory graph with thousands of tiny, garbage-collected strings and the stark, flat line of the StringBuilder approach. The conclusion wouldn’t be a rule; it would be a method. “Here’s the threshold I measured on my machine, here’s the benchmark code, now go measure it on yours.”

This is the difference between handing someone a fish and showing them the sonar. The “what” article hands you a smelly, dead fish. The “why” article puts the sonar in your hands and says, “The fish are over there, but watch out for the rocks.”

Example: The “Why” Behind a React Hook

Look at how most people explain useEffect. They focus on the syntax: the function, the cleanup, the dependency array. They say it “synchronizes with external systems.” But the real “why” is about taming side effects in a declarative rendering model. The mental breakthrough isn’t understanding the array; it’s understanding that you’re not thinking in imperative lifecycle events anymore (mount, update, unmount). You’re synchronizing with state over time.

A why article would deliberately show a bug caused by the old mental model. Let’s write a subscription component that resubscribes on every render because the author forgot the dependency array. Let’s watch the WebSocket connection flicker in the Network tab. Let’s feel the pain of the duplicated messages flooding the console. The fix isn’t just “add an empty array.” The fix is understanding that the effect should only run when the roomId state changes, because the purpose is to sync the connection to the room, not to the component’s render cycle. The code example serves as a miniature case study, not a syntax reference.

The Architecture of a “Why” Article

Writing this way is harder. I know that. It requires vulnerability. You have to admit you built something the wrong way first. You have to expose your dead ends and your flawed assumptions. A sterile “what” article is safe. Nobody ever got yelled at in the comments for pasting the official documentation and summarizing it. But they also never changed anyone’s mental model. They are forgotten the second the tab is closed.

To write a real why piece, you must start from a problem, not a feature. The article’s title shouldn’t be “An Introduction to Kafka.” It should be “We Replaced a Cron Job with an Event Stream and Fixed a Data Race.” The difference is immediate. The first title promises a dictionary entry. The second promises a story with stakes. You can practically see the before-and-after in your head. The reader already knows they’ll learn why Kafka exists, not just what ports it runs on.

The structure follows naturally. You define the initial state, the broken setup. You show the symptoms of failure. The reader, having seen the symptoms in their own projects, is now emotionally invested. Then you introduce the solution not as magic, but as a logical response to the specific pain points. The code you show is the minimal diff that moves the system from broken to functional. The explanation of the syntax is secondary; it’s just the bridge you build to cross the gap you’ve already made the reader want to cross.

What We Lose When We Skip the Why

We lose the ability to debug. If you only know that a React component re-renders when state changes, but you don’t know why React uses referential equality in its dependency arrays, you’ll spend hours wondering why your object prop is causing infinite loops. You’ll copy-paste useMemo and useCallback wrappers until the linter shuts up, and you’ll have a codebase that is slower and harder to read than before you started.

We lose the ability to make architectural decisions. If you only know what Docker commands build and run a container, but you don’t understand why the layered filesystem works the way it does, you’ll build images that are 2GB and wonder why your CI pipeline is so slow. You need to understand that each RUN instruction creates a new layer, and that copying your entire source code before running npm install destroys cache efficiency. That’s a “why” insight. The command reference just tells you the syntax for COPY.

Most critically, we lose the ability to challenge the tools themselves. A developer steeped in “why” can look at a new framework and say, “The problem this solves is real for that specific use case, but its concurrency model is incompatible with our legacy database drivers.” A developer fed only on “what” articles will just install it because the tutorial said to, and will crash the production database at 4:55 p.m. on a Friday. I’ve seen it happen.

An FAQ for the Weary Reader