How to Write a Great Technical Blog Post

Writing is a terrific skill. Being able to communicate clearly through the words you've written will help you grow professionally and personally. Professionally, because the higher up you are in an organization, the more important clear communication becomes. Personally, because writing is thinking.

That's right. It might sound counter-intuitive, because you'd expect writers to do the thinking before the writing, but nearly all writers will tell you that the thinking happens mostly during the writing. Many people find writing difficult not because of grammar or spelling, but because it requires you to filter and sort the jumble of thoughts in your brain to create a coherent argument on the page.

I believe that the difficulty you might encounter writing something mainly boils down to wrong expectations about writing and the lack of a proper process. This article will tackle both points to show you that writing needn't be all that hard. I will focus on technical blog posts in particular, which require a different approach than an opinion piece (or fiction, which is an entirely different beast).

Writing Expectations

If someone says that they're "not a writer," it mostly means two things: they're not a good writer or they don't like writing. And if they don't like writing, it's mostly because they're not good at it.

The reality is that everyone can write. Some people are better than others because they've been longer at it. But not having a lot of experience writing doesn't mean that your writing can't be useful to other people. This is particularly true for technical blog posts that clarify a technical issue.

Case in point: some of the articles that bring in most traffic on the X-Team blog were written by developers who have very little experience writing. Yet they bring in traffic because their articles answer a technical question that many other developers needed answering.

One other thing to realize about writing is that everyone struggles. It's easy to believe that professional writers don't, because you only ever see the finished product. But you can be sure that it took many tries to get to that polished, final result. They too stared at a blank page for a while, thought their writing was terrible, and were tempted to throw it all away and give up.

But they didn't. They persevered and pushed through all the walls they encountered while writing. I believe that this is in part because of a proper writing process.

The Writing Process

When I have to write a technical article, this is the writing process that works for me. If I wouldn't have this process, I wouldn't ever get any writing done. While I encourage you to experiment with different processes, I think that what I'm about to explain is abstract enough to help you too.

We need a writing process because writing is never just writing. Writing an article requires a writer to do many different things. At one point, I'll be looking up what REST stands for (representational state transfer). At some other point, I'll be reading a paragraph out loud to see if it flows well. At some other point still, I might be debating whether or not to add a comma in a particular sentence.

Perhaps ironically, much of the time I spend writing an article is spent on things other than writing.

Step One: Research

The first step of the writing process is my favorite one. I like researching the topic I write about, because I almost always learn something new and because it makes the actual writing easier. I'm much more anxious about writing an article when I haven't done a lot of research versus when I have.

Even when you're already deeply familiar with the topic you'll be writing about, I encourage you to start with at least some research, if only to double-check some of the arguments you'll be making. Not only will it put your mind at ease, but you might learn something that will make your article more interesting.

There are two aspects to the research step: scanning and digging. When I have to write about a topic I'm only vaguely familiar with, I research with the intention to uncover the concepts I want to know more about. I don't try to understand them in detail yet. I just want to find out what I'll need to learn more about later. This step I call scanning.

For example, when writing the Docker vs Kubernetes blog post, I identified these concepts: Docker, Kubernetes, Docker Swarm, container orchestration, virtual machines, containers, Kubernetes manifest, microservices, etc.

Once I've identified these concepts, I research each of them until I deeply understand them. This might mean talking to colleagues, reading articles online, or sometimes even reading a book. This is what I call digging. I take copious notes during the process, which I'll consult heavily when I start writing.

Step Two: Write

Now comes the time to open a blank page and stare at it for a while. The trick is to silence your perfectionist self. Your opening sentence needn't be brilliant right away. Your argument doesn't need to be watertight right away. Just get something down.

If you're struggling to begin, just sit with the page for a while. You'll be tempted to grab your phone or browse away or do anything other than writing. Don't. Just look at the page and let your thoughts roll until you have a first sentence that's good enough.

Personally, I like to write my first draft in one go. It's the most difficult part of the writing process and I want to get it over with quickly. If it takes a few hours, then so be it.

I prefer it this way because it always takes some time to get into a writing flow (which is not too dissimilar to a programming flow). Writing a draft over multiple sessions is inefficient, because you'd need to get back into your flow for every new session.

Step Three: Edit

Once you've written the first draft, let it rest for at least a few hours. Preferably a full day or more. Then look at the article again as if it's your first time reading it. There are two parts to this step as well: holistic and granular editing.

I start with a holistic edit. I read the article and think about any structural changes I might need to make. Does my overall argument make sense? Does each individual argument make sense? Do I need to shift around paragraphs? Is there anything that needs more research?

Then comes the granular edit, where I look at the individual sentences and words. Can I say this in a better way? Do I need a connector between these two paragraphs? How can I avoid repeating this word? Should I add a comma here? This step comes after the holistic edit, because it doesn't make sense to look at these details when you still need to make structural changes to your article.

This is also when I try to come up with the best possible headline. Up until this point, I've used a placeholder headline. The placeholder headline rarely becomes the final headline. I tend to write around ten or more different headlines before I settle on one.

Headlines are supremely important and, particularly in a technical blog post, should tell people what they can expect from your article.

That's the process. Research (scan and dig), write, and edit (holistically and granularly). I hope this will make writing at least somewhat easier for you. If you have a different writing process, please feel free to share it in the comments 👇.