Writing About Code Has Made Me Better at Writing Code

Most developers treat technical writing as something you do after you know what you're talking about.

I've started thinking about it the other way around.

Sometimes I don't realize how poorly I understand something until I try to explain it.

You can spend hours working with a piece of technology and feel completely comfortable with it.

Then somebody asks:

Why does it work that way?

And suddenly your brain goes:

Well… it just does.

That's usually the point where you discover the difference between recognizing something and actually understanding it.

Code lets you hide behind working software

Programming has an interesting loophole.

Your code can work even when your mental model is incomplete.

You can know that:

await db.query(...)

works.

You can know where to put it.

You can know how to handle the response.

But that doesn't necessarily mean you understand:

what happens when the connection drops
how the connection pool behaves
when the promise resolves
what happens under concurrent requests
how the database handles the query
what failure actually looks like

And that's fine.

Nobody needs to understand every abstraction underneath every line of code they write.

But the gaps become obvious when you attempt to explain the system to another person.

Writing removes the autocomplete from your understanding.

Explaining something forces you to find the missing pieces

Let's say I want to write:

"A database connection pool improves performance."

Easy sentence.

Then I ask myself:

Why?

Because we're reusing connections instead of creating one for every request.

Okay.

Why is opening a new database connection expensive?

Now we're talking about networking, authentication, resource allocation and connection setup.

What happens if the pool is exhausted?

What decides how many connections should exist?

Can too many connections make performance worse instead of better?

Five minutes ago I thought I was writing one paragraph.

Now I'm reading PostgreSQL documentation.

That's what I like about writing.

It exposes the edges of what you actually know.

Tutorials are especially unforgiving

When you're coding alone, you can skip steps mentally.

You know that before this:

npm run dev

you already:

npm install

created .env, configured the database and probably fixed three errors you no longer remember.

The reader doesn't know any of that.

So when you're writing a tutorial, you have to reconstruct the real sequence.

That forces you to think more carefully about:

dependencies
assumptions
defaults
edge cases
setup
failure states

You begin noticing complexity you've learned to ignore.

I've had several situations where writing about a workflow made me think:

Why does this require so many steps in the first place?

Which is also where product ideas tend to appear.

Writing is surprisingly good product research

This one wasn't obvious to me initially.

When you try to explain a technical problem properly, you naturally start researching how other developers solve it.

Suppose I'm writing about deploying a backend.

I might start with:

"Deploying a backend requires…"

Then I need examples.

So I start looking at:

Docker
Railway
Render
VPS deployments
CI/CD
migrations
reverse proxies
environment management
health checks

And while reading, patterns start showing up.

Everyone has slightly different solutions to the same underlying problems.

You start noticing where tools overlap.

Where workflows are unnecessarily complicated.

Where developers complain.

Where documentation repeatedly has to explain the same thing.

You weren't doing market research.

You were trying to write a decent article.

But you end up learning a lot about the market anyway.

Writing also generates ideas

One article tends to create five more.

You start writing about logging.

Then you realize error reporting deserves its own article.

That leads to observability.

Then production debugging.

Then distributed tracing.

Then suddenly you have a backlog of topics you didn't have yesterday.

It's basically recursion for ideas.

The most useful part is that the ideas aren't coming from:

"What should I post today?"

They're coming from questions you naturally encountered while trying to understand something.

Those tend to make better articles.

It changes how you read documentation

Before I started writing more often, documentation was usually transactional.

I had a problem.

I searched for the answer.

I copied the relevant mental model into my brain.

Then I left.

Now I notice more things.

Why did the documentation explain this concept before that one?

What misconception are they trying to prevent?

Why is this warning here?

What edge case was common enough that somebody decided it deserved an entire section?

Good technical documentation isn't only teaching you the technology.

It's showing you where people usually misunderstand it.

That information is incredibly useful.

It makes vague opinions harder to keep

Developers have plenty of opinions.

"This framework is slow."

"Microservices are overkill."

"SQL is better."

"Serverless is expensive."

"X is easier than Y."

Those opinions are easy to say.

They're much harder to publish when you know another developer can ask:

Based on what?

Writing forces you to qualify things.

Instead of:

Serverless is expensive.

You start writing:

Serverless can become expensive for workloads with these characteristics…

Which is a much better statement.

You stop trying to sound certain and start trying to be accurate.

That's useful far beyond writing.

You don't have to become a "content creator"

This is probably the part developers hate.

The moment somebody says:

You should write.

it starts sounding like:

Build your personal brand. Post three times every day. Optimize engagement.

I'm not talking about that.

You can write once a month.

You can have 20 readers.

You can publish something that gets absolutely no traction.

The value isn't only distribution.

The process itself is useful.

You are forcing your brain to turn:

I think I understand this

into:

Here is exactly how I think this works.

Those are very different things.

The simplest writing habit I've found

When something makes me stop while coding, I write it down.

That's it.

Things like:

Why did this migration fail?

Why does this API behave differently in production?

Why are these two tools solving the same problem differently?

Why does this configuration exist?

What actually happens when this command runs?

You don't need the article immediately.

Just keep the questions.

When you eventually sit down to write, you're not staring at a blank editor trying to invent a topic.

You're answering something that genuinely made you curious.

And curiosity is usually a better starting point than a content calendar.

Writing is part of learning

I used to think the sequence was:

Learn → understand → write

Now I think it's closer to:

Learn → write → discover what you don't understand → learn more → rewrite

And the loop keeps going.

The article is almost a side effect.

The real output is a clearer mental model.

So if you're learning something, building something or repeatedly solving the same technical problem, try writing about it.

Even if nobody reads it.

You'll probably discover something you didn't know you didn't know.