Home Notes Popular RSS

April 10, 2024

What makes a great technical blog

writing

I want to explain why the blogs in My favorite technical blogs are my favorite. That page is solely about non-corporate tech blogs. So this post is too. I'll have to make another list for favorite corporate tech blogs.

In short, they:

  • Tackle hard and confusing topics
  • Show working code
  • Make things simpler
  • Write regularly
  • Talk about tradeoffs and downsides
  • Avoid internet slang, memes, swearing, sarcasm, and ranting

Tackle hard and confusing topics

There are a number of problems in programming and computer science where otherwise knowledgeable programmers have to start mumbling about, or revert to cliches or group-think, because they aren't sure.

These are the best topics you can possibly dive deep into. And my favorite writers do exactly this.

They write about durability guarantees of disks and filesystems. They write about common pitfalls in benchmarking. They write about database consistency anomalies. They write about threading and IO models.

And they write about it by showing concrete examples and concrete logic so you can learn how to stop handwaving on the topic.

Their writing helps you come out with a useful mental model you can apply to your own problems.

And you know, sometimes it's not about about the topic being obscure. Good writers have the ability to tackle a boring topic in an interesting light. Maybe by digging deeper into a root cause. Or showing you the history behind the scenes.

Moreover, my favorite writers don't know everything. But they also don't pretend to know everything. They're quick to admit they don't understand something and ask for help from their readers.

Show working code

I love to see complete working code in a post. In contrast there are many projects that start out simple and people write an article that covers the project at a high level. But they keep working on the project and it becomes more complex.

It's not always easy to follow commits over time.

Eli Bendersky and Serge Zaitsev are particularly great at developing small but meaningful projects in a single post or short series.

On the other hand, if people only did this, we wouldn't hear about the development of long-running projects like V8 or Postgres. So I guess this style has limits. And I don't penalize people talking about long-running projects for not showing working code.

Make things simpler

One of the marks of a good writer is that you can make complex topics simple. And not just by being reductive. Though sometimes even being reductive is useful for education.

In contrast I sometimes see articles by less experienced writers and I marvel how they make a simple topic so complex. I recognize this because I was absolutely like that 10 years ago, if not 5 years ago.

Write regularly

My favorite blogs typically get a new post at least once a month. Some people, like Murat, write once a week.

I think the practice probably does improve your writing but mostly it's that they keep my attention by publishing regularly!

Talk about tradeoffs and downsides

Nothing builds trust like talking about the issues with something you built. No project is perfect. And to ignore the downsides risks seeming like you don't know or understand them.

So the writers I like the most talk about decisions in context. They talk about the good and the bad.

Avoid internet slang, memes, swearing, sarcasm, and ranting

There's no way I can think of talking about this without sounding super lame.

One thing I've noticed, particularly among younger colleagues, is the use of memes or swearing or using 4chan slang or using sarcasm. I used to write like this 10 years ago too.

There is a chunk of your audience who won't care. The problem is that there's also a chunk of your (potential) audience who definitely does care. There's even a chunk of your audience who may not care but just won't understand (i.e. non-native English speakers).

I have friends and folks I respect who write very well. But that also are also overly, unnecessarily edgy when they write. I don't like sharing these posts because I don't want to unnecessarily offend or turn off people either.

Closing thoughts

It would be boring if everyone wrote the same way. I'm glad the internet is fun and weird. But I wanted to share a few things that go into my favorite technical blogs that I'm always happy to refer people to.