Introduction

In the first part of this series, I argued that programming is really about building a shared theory in our heads, not just reading the code. Now let’s zoom in on a related trap: confusing the documents and diagrams—the map—with the actual knowledge—the theory. If “just read the docs” left you wanting, this post explains why.

Maps vs. Theory

Alfred Korzybski said “the map is not the territory.” In software, the map is our architecture diagrams, wiki pages, and README files. The territory is the running system and all the unwritten context behind it. When you mistake one for the other, you’re flying blind.

Theory is what lets you navigate without staring at the map every second. It tells you which services matter, why a pattern emerged, or which hack is holding things together. Docs are at best breadcrumbs leading you toward that theory.

Where Maps Fall Short

Even good maps miss the messy parts:

• Outdated diagrams: The diagram shows four services, the codebase has seven. Now you’re debugging ghosts.
• Simplified flows: Sequence diagrams skip retries, timeouts, and feature flags—the stuff that bites you in prod.
• Missing intent: A doc might say “use service X,” but not why we chose it or what trade-offs we made.
• Hidden constraints: Security rules, compliance hacks, or business quirks rarely make it onto the page.

Reading the docs is like looking at a subway map without riding the train—you get the lines, but not the noise, delays, or weird station smells.

When Maps Help

Maps aren’t useless. They’re great for:

• Orientation: A high-level architecture sketch helps new folks know which repo to open first.
• Shared vocabulary: A glossary or ADR keeps everyone using the same words for the same things.
• Decision snapshots: Docs can capture why something was done, even if the details drift later.

But maps only help if everyone knows they’re approximations. Treat them like clues, not gospel.

Building Real Theory

To keep your mental models sharp:

• Walk the territory: Pair, shadow, run the system locally. Experience trumps diagrams.
• Tell stories: Share the “why” in meetings, code reviews, and slack threads. Theory travels through conversation.
• Update maps sparingly: Keep docs high-level and easy to maintain. If it’s not worth updating, it probably doesn’t need to exist.

Final Thoughts

Maps guide, but theory navigates. Use docs as starting points, then build the real understanding with your team. When the system changes—and it always does—the folks with theory adapt, while the map-readers get lost.

Stay tuned for part three, where we talk about practical ways to bridge the gap between the docs on disk and the theory in your head.

If you enjoyed this post, follow me on the platforms linked at the bottom of this page.