{ Soham Kamani }

About Blog Github Twitter

🌙
☀️

How To Write Reader-Friendly Technical Blog Posts

Writing good blog posts is hard.

By “good blog posts”, I mean articles that your readers will understand and gain something from (especially those that are new to the subject matter you’re writing about).

In this post, I will summarize the processes and techniques I use to write blog posts that I want my readers to learn from.

I’ve written around 70 blog posts on this website as of this date, and a few more elsewhere. Some of them were well received, and others not so much. I’ve tried to distill what I think is important in writing blog posts or tutorials with a technical subject matter, so that you can make it as reader-friendly as possible.

What Do You Write About?

First do it, then explain it

Anything you write about has to be something you’re familiar with, or have worked on before.

This may seem obvious at first, but many people (including me) have made the mistake of thinking that they can write about something right after trying it out for the first time themselves.

Normally for every new thing I learn, there’s this brief period where I feel like I understand everything. Invariably, after a little more experience I come to terms with how little I actually know.

The best tutorials or articles that I’ve written about came from subjects that I knew well enough to feel confident explaining to others.

there's a zone where you're able to write best once you have enough experience

For example, I feel comfortable writing this blog post because I’ve been writing consistently for the last few years to the point where I feel like I know enough to share my process with others.

But this begs the question: Who are the others that I’m explaining to?

Who Are You Explaining To?

It’s not about you

If your intention is to write something that will help others, you have to first decide who they are, what they know, and more importantly, what they don’t.

For example, in my post about RSA Encryption in Node.js, I assumed that the reader would:

  1. Have some experience with Node.js
  2. Have heard about RSA encryption, but not know how it’s implemented
  3. Want to know how to implement the RSA algorithm in Node.js

Consequently, the article spends less time explaining patterns and semantics in Node.js, and more time explaining RSA encryption and decryption in detail, with some code showing how to implement it in Node.js.

I skipped out instructing the reader on how to create a new project folder, or install necessary libraries because I assumed that would already have experience with that.

Having assumptions about who your readers are beforehand will help you trim down your post to only have content that your readers will find helpful.

For this post, I am making the assumption that the reader is someone who:

  1. Has just started out writing, or wants to start writing on their blog
  2. Knows how to set up their own blog
  3. Has some idea what to write about, but isn’t sure how to structure it or make it “production ready”

Which is why this article focusses on the process of writing, and not on how to get the best topics, or how to set up a new blog.

Introductions Are More Important Than You Think

The introduction is an elevator pitch for the rest of your article.

When a reader lands on your blog post, they’ll want to know what they’ll be reading about.

This is what your introduction is for: It should let the reader know what will be covered, why they should be interested, and where they will end up after reading you post.

If my blog post contains sample code, I usually add a link to it in the introduction itself, for those who want to skip the explanation and just see the code.

Divide Your Post Into Sections

The human brain is not good at processing large chunks of information. Breaking you post into bite-size sections of 3-4 paragraphs each will do a great deal in reducing the mental burden your reader will face.

The same goes for each paragraph, which shouldn’t be more than 2-3 sentences. Overall, an article with healthy section will have this approximate shape:

articles should be divided as pictured here

You don’t have to go overboard with this, but just be aware of whenever a block of text becomes too large and break it up into smaller chunks. Speaking of which, one of the best ways to interject blocks of text is: …

Add Illustrations

It’s hard to overstate just how much a good illustration can impact your readers understanding of what you’re trying to explain.

If you’re trying to explain a concept with multiple moving parts, an illustration can do wonders to untangle complex interactions and relationships between different components.

There are, however, a few caveats that you should be aware of:

  1. Any picture or diagram should always be in context of what’s currently being discussed in the surrounding text. Otherwise, it brings confusion rather than clarity.
  2. Try to avoid third party diagrams, and prefer to make your own wherever possible. I normally use free tools like Draw.io or Excalidraw, which are super-easy to use.

I consider code snippets a form of illustration as well, and the same guidelines apply to them as well (being in context, and being your own).

When adding a snippet after explaining a concept, it’s best to only have the snippet execute what you were explaining. For example, this code snippet from my blog post on SQL Transactions in Node.js only demonstrates the concept of conditionally rolling back a transaction. The rest of the code is replaced by placeholder //... comments:

code snippet is in the context of what is being explained

Read More, Write More, and Listen More

Experience is the best teacher

As with anything else in life, the more you practice something, the better you get at doing it. If you really want to get better at writing, the best thing you can do is write more!

By writing more, you’ll be able to turn thoughts into sentences more efficiently. In addition to that, you’ll understand what you’re trying to explain better than you did before. I found that every time I tried explaining a concept in writing, that concept stuck much more clearly in my head.

But writing alone is not enough to improve yourself. A great way to know what exactly constitutes a great article or blog post is to read some great blog posts yourself (and the internet has no shortage of these).

Go read any well respected blog in your area of interest, and when you find an article you really like, try reading it again and ask yourself what you liked about it. Was it because it was entertaining? Was it because the illustrations used were so creative? Maybe it just felt effortless to read? In any case, these insights will give you clues on how you can improve your own writing.

Another great way to know if you’re going in the right direction is to get feedback. After writing something, get a friend or a colleague to read what you’ve written, and tell you how they felt about it. Bonus points if they’re unfamiliar with the topic beforehand.

The last thing I’d like to say is to just have fun with it. Yes, it takes effort and practice to make a good quality article or blog post, but that doesn’t mean it has to be boring. If you have any second thoughts on whether or not you should go on and write that blog post you’ve been putting off, maybe my other article will help change your mind.


Like what I write? Join my mailing list, and I'll let you know whenever I write another post. No spam, I promise!

Comments

Soham Kamani

Written by Soham Kamani, an author,and a full-stack developer who has extensive experience in the JavaScript ecosystem, and building large scale applications in Go. He is an open source enthusiast and an avid blogger. You should follow him on Twitter