There’s a ritual that plays out in every engineering team, in every open-source project, in every homelab notebook across the internet. Someone hits a wall — a cryptic error, a config file that makes no sense, a dependency chain that collapses like a house of cards. They spend hours, sometimes days, untangling it. And then, at the end, they sit down and write it up. Not because anyone asked them to. Not because there’s a ticket for it. But because they have to. Because the act of writing it down is the moment it finally clicks.

I’ve started to believe that this isn’t a side effect of learning. It is the learning.

The Illusion of Understanding

We’ve all done it. You follow a tutorial, the commands work, the service comes up, and you move on. You feel good. You feel like you understand it. Then two weeks later you need to do something slightly different and you’re staring at the same blank terminal, the same empty config file, with absolutely no idea where to start.

What happened is that you confused recognition with understanding. You recognized the steps. You could follow them. But you never built the mental model — the web of cause and effect that lets you reason about the system when things go off-script.

Writing documentation forces you out of recognition mode. You can’t document something you only half-understand. The gaps become immediately, painfully obvious. “Wait, why does this flag exist? What happens if I change this value? What’s the actual difference between these two directives?” The questions you can gloss over when you’re just following along become impossible to ignore when you’re trying to explain.

Rubber Ducking, Scaled Up

Programmers know about rubber duck debugging — the practice of explaining your code line by line to an inanimate object, and in the process, finding the bug. Writing documentation is rubber ducking for your entire knowledge base.

When you write a tutorial, you’re not just recording steps. You’re making a series of implicit claims: “This is why this step matters. This is what would happen if you skipped it. This is how this connects to the thing before and the thing after.” Each of those claims is a test of your understanding. If you can’t make the claim, you don’t understand it yet.

This is why the best documentation reads like a conversation. Not because the author is trying to be casual, but because they’re working through the logic in real time, anticipating the reader’s confusion, and addressing it. That process of anticipation is itself a deep form of comprehension.

The Homelab Notebook

I keep a running document of everything I set up in my homelab. Every service, every config change, every “oh right, I need to remember this for next time.” It started as a practical thing — I got tired of re-solving the same problems. But over time it became something else: a map of my own understanding.

Looking back through old entries, I can see exactly when I started to get something. The early entries are mechanical: “Run this command, edit this file, restart this service.” No explanation, no context, no “because.” They’re just recipes.

Later entries start to include the reasoning. “I’m using a bind mount here instead of a volume because I need to edit the config from the host.” “This port conflicts with the other service, so I’m mapping it to 8081 on the host side.” The documentation got better because my understanding got deeper.

And here’s the thing — I’m not sure which came first. Did I understand it better and then write better docs? Or did the act of trying to write better docs force me to understand it better? I genuinely think it’s the latter, or at least, it’s a virtuous cycle where each feeds the other.

Documentation as Generosity (to Your Future Self)

There’s a lot of talk about documentation being a gift to others. And it is. Every time you write a clear explanation of something tricky, you’re saving some stranger hours of frustration. That matters.

But honestly? The person you document for most is you, six months from now. Future you who doesn’t remember the subtle gotcha. Future you who set up that service at 2 AM and can’t remember why you chose that particular configuration. Future you who is, functionally, a different person.

I think about this every time I find a blog post that solves my exact problem at the exact moment I need it. The person who wrote that post had no idea I existed. They were writing for themselves. And it saved me. That’s the beautiful, accidental generosity of putting your learning into words.

Start Before You’re Ready

The biggest barrier to writing documentation is the feeling that you don’t know enough yet. That you need to fully understand something before you can explain it. That you need to be an expert.

This is backwards. You don’t write documentation because you’ve finished learning. You write it as part of learning. The imperfect explanation, the thing you almost understand, the tutorial that covers 80% and admits the other 20% is a mystery — that’s not failure. That’s the process.

Some of the most valuable posts I’ve ever read online are written by people who are clearly figuring things out as they go. They say things like “I’m not entirely sure why this works, but here’s what I’ve observed” or “If someone knows the deeper reason, I’d love to hear it.” That honesty is more useful than a polished explanation that papers over the gaps.

The Takeaway

If you want to learn something deeply, write about it. Not after you’ve mastered it. While you’re learning it. Write the tutorial. Write the blog post. Write the README. Write the comment in the code that explains why, not just what.

You’ll find that the act of writing exposes every gap in your understanding. And once you can see the gaps, you can fill them. And once you’ve filled them, you actually know something — not just how to follow steps, but how the system works, why it works that way, and what happens when it breaks.

The best documentation isn’t written by experts. It’s written by people who were just confused enough to know what needs explaining.

So the next time you solve something tricky, don’t just move on. Write it down. Your future self — and some stranger on the internet — will thank you.