Last week, I spent three hours trying to understand a piece of code I wrote one year ago. Three hours. For my own code.
I was absolutely certain I remembered how it worked. The logic seemed familiar, the variable names rang a bell, and I had that confident feeling of “oh yeah, this one.” But when I actually sat down to modify it, nothing made sense. The architecture decisions felt random, the edge cases were mysteries, and the business logic might as well have been written in ancient Greek.
This is what psychologists call the Mandela Effect in action—when we’re collectively convinced we remember something that never happened, or happened differently than we think. You know, like being sure the Monopoly Man wears a monocle (he doesn’t) or that the Berenstain Bears were spelled “Berenstein” (they weren’t).
As engineers, we experience our own version of this constantly. We’re convinced we’ll remember why we chose that particular data structure, or how that complex algorithm works, or what that cryptic variable name actually represents. Spoiler alert: we won’t.
Why Your Brain Is Working Against You
Here’s the uncomfortable truth: our brains are designed to forget. They have to be. We process massive amounts of information every day—new frameworks, changing requirements, evolving codebases, countless meetings, and endless Slack threads. If we held onto every detail, we’d be paralyzed by information overload.
So our brains do what they do best: they fill in gaps with assumptions, compress complex information into simplified patterns, and quietly discard what seems unimportant in the moment. This works great for survival, but it’s terrible for engineering.
The result? That brilliant solution you crafted becomes a puzzle you can’t solve. The elegant architecture you designed becomes a maze you can’t navigate. The clever optimization you implemented becomes a bug you can’t trace.
Documentation: Your Time Machine
Good documentation isn’t just about helping others—it’s about helping your future self. It’s a time machine that lets you communicate with the person you’ll be in six months, when the context has faded and the details have blurred.
Think of it as leaving breadcrumbs for yourself, except these breadcrumbs don’t get eaten by birds or washed away by rain. They’re permanent markers that say “here’s what I was thinking, here’s why I made this choice, and here’s what you need to know to pick up where I left off.”
I’ve learned this lesson the hard way more times than I’d like to admit. Every time I skip documentation because “I’ll remember this,” I’m essentially setting a trap for my future self. And my future self always falls for it.
The Onboarding Test
Here’s a simple test I use: could someone completely new to the project understand this system from the documentation alone? Not just the what, but the why. Not just the happy path, but the edge cases. Not just the current state, but the evolution that led here.
If the answer is no, then I’m not just making life difficult for potential new team members—I’m making life difficult for myself when I inevitably forget the context.
Good documentation serves as a mental prosthetic. It extends our limited working memory and compensates for our tendency to forget. It turns tribal knowledge into institutional knowledge, and makes complex systems navigable even when their creators have moved on.
What Actually Matters
The best documentation I’ve encountered isn’t comprehensive—it’s strategic. It focuses on the decisions that aren’t obvious from reading the code. It explains the constraints that shaped the solution. It captures the alternatives that were considered and rejected.
Here’s what I try to document:
The Why Behind the What: Code shows what you did, but rarely why you did it. Document the business requirements, technical constraints, and tradeoffs that influenced your decisions.
The Path Not Taken: What other approaches did you consider? Why did you reject them? This saves future developers (including yourself) from re-exploring dead ends.
The Gotchas: What surprised you during implementation? What assumptions turned out to be wrong? What edge cases emerged that weren’t obvious upfront?
The Dependencies: What external factors does this code rely on? What happens if those factors change? What’s the blast radius of modifications?
Making It Sustainable
The biggest barrier to good documentation isn’t time—it’s habit. Writing documentation feels like overhead when you’re in the flow of coding. The solution isn’t to document everything; it’s to document the right things at the right time.
I’ve found that the best time to document is right after you’ve solved a problem, when the context is fresh but the struggle is still memorable. That moment when you finally understand the solution is the perfect time to explain it to your future self.
AI tools are also changing the game here. They can generate basic documentation from code structure and comments, maintain consistency across projects, and even help identify gaps in existing docs. But they can’t replace the human insight of why you made certain decisions—that’s still on us.
The Compound Effect
Documentation has a compound effect. Each piece you write makes the next piece easier. Each system you document thoroughly becomes a reference for similar systems. Each decision you capture becomes a precedent for future decisions.
Over time, you build up a knowledge base that makes you faster, not slower. Instead of re-solving the same problems repeatedly, you’re building on previous solutions. Instead of second-guessing past decisions, you’re learning from documented reasoning.
Start Small, Stay Consistent
You don’t need to document everything perfectly from day one. Start with the decisions that surprised you or the problems that took longer than expected to solve. Document the moments when you thought “I should remember this” or “this might not be obvious to others.”
Make it part of your workflow, not an afterthought. When you’re writing a complex function, spend five minutes explaining why it exists. When you’re making an architecture decision, capture the alternatives you considered. When you’re fixing a tricky bug, document what made it tricky.
Your future self is counting on you. Don’t let them down.
The best time to plant a tree was 20 years ago. The second best time is now. The same goes for documentation—start today, and your future self will thank you for it.