There’s a particular kind of loneliness that comes with writing documentation.

You spend an hour crafting the perfect README.md. You add sections. You include examples. You write a troubleshooting guide for problems you personally encountered at 2 AM on a Tuesday. You add a FAQ. You proofread it. You publish it to GitHub.

Three people read it. One of them is you, six months later, trying to remember how the thing works.

And yet we keep doing it. Why?

The Myth of the Grateful Reader

When I started self-hosting services — Pi-hole, WireGuard, a media server, the usual homelab suspects — I kept running into the same wall: terrible documentation. Or no documentation at all. A GitHub repo with a single line: docker run -d everything.

So when I write about these things, I try to be the documentation I wish existed. I write tutorials with prerequisites, step-by-step commands, explanations of why each step matters, and a troubleshooting section for all the ways I personally broke things.

Selfishly, I’m writing them for future-me. Altruistically, I’m writing them for the person who’s Googling at 2 AM, just like I was.

But here’s the thing nobody tells you about writing documentation: the act of writing it teaches you more than the act of reading it ever could.

Rubber Ducking, But Make It Permanent

There’s a well-known debugging technique called “rubber duck debugging” — you explain your code line by line to a rubber duck, and somewhere in the explanation, you find the bug.

Writing documentation is rubber duck debugging for your entire understanding of a system. The moment you try to explain why you set Restart=always in a systemd service file, you’re forced to actually understand what happens when it doesn’t have that directive. You can’t hand-wave your way through a tutorial.

Or rather, you can — but your readers will find you. They’ll leave a comment. They’ll open an issue. They’ll send you a polite email that says “Step 4 doesn’t work on Ubuntu 24.04” and you’ll realize you made an assumption you didn’t even know you were making.

Documentation is the crucible where vague understanding gets forged into actual knowledge.

The Documentation Paradox

Here’s the paradox: the projects that need documentation the most are the ones that have the least of it. And the reason is simple — the people who build things are rarely the people who enjoy writing about them.

Building is immediate. You type commands, things happen, containers spin up, services respond. There’s feedback. There’s dopamine. There’s the sweet satisfaction of a green checkmark in your terminal.

Writing documentation is delayed gratification in its purest form. You might not get a single comment for months. Your analytics will show pageviews in the single digits. The GitHub stars will go to the project with the flashy README full of badges, not the one with the thorough getting-started guide.

And still, the thorough documentation is what saves people. It’s the difference between someone getting your project working in ten minutes versus giving up and finding something else.

Writing for the One Person

I have a theory that every piece of good documentation is written for exactly one person. Not “users” (plural, abstract, faceless). One person. A specific human being who is frustrated, confused, and running out of patience.

Maybe that person is you, six months ago. Maybe it’s a colleague who just inherited your project. Maybe it’s a stranger on the internet whose search query matched your blog post title.

When I write, I imagine that person. I imagine them sitting at their desk, slightly annoyed, looking for a clear answer. I try to be the voice that says: “Hey, I’ve been here. It’s not you. Let me walk you through it.”

That’s the tone I aim for. Not “Here is the definitive guide.” More like: “Here’s what worked for me. Your mileage may vary. Let me know if something breaks.”

The Quiet Satisfaction

I won’t pretend documentation is glamorous. It won’t go viral. Nobody’s going to make a documentary about your docker-compose.yml comments.

But there’s a quiet satisfaction in it. In knowing that something you wrote helped someone, even if you never hear about it. In knowing that the next time you need to set up that service, the answer is waiting for you in your own words.

We write documentation because we’ve all been on the other side of the search results. We’ve all landed on a blog post from 2019 that solved our exact problem. We’ve all thought: Thank you, stranger. I don’t know who you are, but you saved my evening.

And then we go write our own. Not for the applause. Not for the pageviews. But because the cycle continues, and someone has to be the stranger who helps.

That’s the art of writing documentation nobody reads. You write it anyway. And somewhere, at 2 AM on a Tuesday, someone finds it.

And that’s enough.