The Kindest Thing You Can Do for Tomorrow’s Self

There’s a moment that every developer knows intimately. It’s 2 AM, you’re staring at a config file you wrote six months ago, and you have absolutely no idea what you were thinking.

The variable names might as well be hieroglyphics. The comments — if they exist at all — say things like // TODO: fix this later or the ever-popular // don't touch this, it works. You are, in every meaningful sense, a stranger to your own work.

We’ve all been there. And if we’re honest, we’ve all been on both sides of that equation — both the confused reader and the negligent author.

The Empathy Gap

Here’s what I’ve come to believe: writing good documentation is not a technical skill. It’s an act of empathy. It’s the practice of sitting down with your current knowledge and deliberately setting it aside so you can imagine what it’s like to not know what you know.

That’s harder than it sounds. The moment you understand something deeply, your brain starts to compress it. The steps that once felt confusing become obvious. The gotchas that tripped you up become invisible. Psychologists call this the “curse of knowledge” — once you know something, it’s almost impossible to remember what it was like before you knew it.

Good documentation fights that curse. It’s a deliberate act of time travel, where you reach back across the gap between your expert self and your confused self and build a bridge.

It’s Not Just About Code

But this isn’t really a post about code documentation, is it? It’s about the broader practice of leaving breadcrumbs — for ourselves, for each other, for the strangers who will one day inherit the systems we’ve built.

I think about this every time I set up a new server. I create a NOTES.md file in the root directory. It’s not fancy. It doesn’t follow any template. It just answers the questions I know I’ll have later:

• Why did I choose this particular setup?
• What are the non-obvious things that could go wrong?
• Where did I deviate from the standard tutorial, and why?
• How do I recover when (not if) something breaks?

These notes have saved me more times than I can count. They’re the kindest gift I’ve ever given myself — a letter from a past version of me who took five minutes to be thoughtful.

The Maintenance Mindset

There’s a quiet philosophy embedded in this practice. It says: I believe someone will need this later, and I believe that someone deserves help.

That’s a radical stance in a culture that rewards speed over care, shipping over refining, the new over the maintained. We celebrate the launch, the deploy, the big reveal. Nobody throws a party for the person who wrote a clear README.

But here’s the thing — the README is what survives. The launch is a moment. The documentation is a relationship.

Small Acts of Digital Compassion

I’ve started thinking of documentation as a form of digital compassion. It’s small, often invisible work that makes someone’s day slightly less frustrating. It’s the comment that explains why, not just what. It’s the commit message that captures the reasoning, not just the change. It’s the runbook that assumes the reader is tired, stressed, and working at 3 AM.

And it’s not just for strangers. Some of the best documentation I’ve ever read was written by someone who knew, with certainty, that they would be their own reader. They wrote it for themselves, six months from now, when the details had faded and the context had evaporated.

That’s not vanity. That’s self-compassion. That’s looking at your future self and saying: I know you’ll be tired. I know you’ll have forgotten. Let me help.

Start Small

If this resonates with you, here’s my challenge: the next time you finish a project, a setup, or a fix, take five extra minutes. Write down what you learned. Capture the gotchas. Explain the reasoning.

Don’t aim for perfection. Don’t wait until you have time to write the “real” documentation. Just leave a trail of breadcrumbs — messy, imperfect, human breadcrumbs — for the next person who walks this path.

That person might be a colleague. It might be a stranger on the internet. It might be you, six months from now, at 2 AM, staring at a config file with no memory of why you set it up this way.

Be kind to that person. They deserve it.

And if you’re reading this at 2 AM right now, trying to figure out something you built months ago — I’m sorry. I’ve been there. We’ve all been there. Maybe this is your sign to write those notes now, while the context is fresh, for the next time.