How to Write a Blog Post

and Why You Should

8 min readMar 2, 2021

This is a simple post on how to write a blog post, based on my own experiences over the last few years writing numerous posts, mainly on technology and innovation.

It’s not trying to teach how to get views or how to make money — it’s more about how to plan the structure and content of a post.

Types of blogs

I see two main types:

Opinions — posts with your opinions, commentary or predictions on a subject e.g. “Best JS Frameworks in 2021”, “How to Write a Blog Post” or “Why Wandavision Is The Best Show Since The Mandalorian”.
Tutorials — how to do something. I’ve generally found that tutorials have longer lives; my top-viewed posts are all tutorials that have organically gotten relatively large amounts of views over time, mainly from Google search results.

What to blog about

It’s best to write about something that you are passionate about, or at the very least are knowledgable about. Medium is full of posts that are obviously (badly) written with the single aim of trying to make money from Medium’s partner program, and if that’s what you’re after go ahead, but the best advice is to write about something you like yourself and that you’d like to share with others.

The Title

The title should be like Ronseal — does what it says on the tin. If it’s a blog about how to make an AR shooting game, call it How to Make an AR Shooting Game.

Ideally it should draw attention, but stay away from clickbait titles like Top 7 Reasons Your Boss Gets Paid More Than You. The internet has enough content like that, we can do better.

The Image

You’re going to need a main image — it helps draw attention and will likely be what people see first when shared on social media platforms.

Make sure you understand any license requirements — are you allowed use the image, and do you have to attribute credit in the blog? There’s a few great sites with free images, including pixabay.com and pexels.com. If you have design skills and can make your own image, that’d also be great.

I wrote a series of iOS and Android tutorials for a course I was giving, and I used the same style of image for each post. Not necessary but can help maintain consistency with your readers, and establish a brand if that’s what you’re aiming for.

Images from https://appsandbiscuits.com/

Picking an image can be difficult so if you’re really struggling to pick one my advice is to not stress about it if you can’t find the perfect image — just pick something generic and use that.

The Introduction

Introduce what the post is about, and also establish your own credentials so reader has an idea that you know what you’re talking about. Take this post:

This is a simple post on how to write a blog post (what the post is about).
based on my own experiences over the last few years writing numerous posts, mainly on technology and innovation (establishing credentials).

Context

If necessary, add additional context — don’t presume that your readers know anything about what you’re telling them.

Let’s say you’re going to write an in-depth tutorial on Kubernetes — write a paragraph after the intro explaining what Kubernetes is and why this is of interest.

A sample from one of my posts where I give some additional context on ListViews, before we actually start learning how to use one:

ListViews in Android are one way to display a scrolling list of information — like a list of news items, a list of recipes, a list of delicious biscuits, whatever! They’re one of the basic building blocks of a lot of apps and essential to understand if you want to make your own apps. This tutorial will show you step-by-step how to use them.

Tell the reader what is needed

For tutorial posts, before you get into the steps, detail what’s needed — e.g. an AWS account, a knowledge of Javascript, or whatever. If you really are doing something on Kubernetes, maybe suggest a strong drink and lots of patience.

Here’s an example from one of my tutorials on how to make an Amazon Alexa Skill:

What do you need to start?

An Amazon Developer account (Amazon’s developer website), free to setup, to create a the Skill.
An Amazon AWS account (Amazon’s cloud services platform), free to setup, to create a Lambda function. (more on Lambda in a minute!)
All the tools are web-based, so no extra software needed
You don’t need an actual Amazon Echo, though one would be handy for physical testing … and for showing off afterwards!
An idea!! The most important bit! Your Skill is basically an app and just like apps, they need a good use-case. Today, I’ve decided to make a Skill to give interesting Irish Mythology facts!

Step by Step Instructions

Again, if for a tutorial — write it all out simply, step by step. Presume again that your audience is new to this. If it’s going to be complex, explain what you’re going to go through at the start, almost like a table of contents. Here’s a sample from another one of my posts:

Game Design

The objective of the game is to get as many points as possible in 60 seconds by shooting down virtual 3D objects, that are displayed all around the player, via the camera view. So the main things we need are:

Buttons to allow the user to fire different, fun, missiles. Each button should also have fun graphics.
An image for a “target” in the centre of the screen to help aiming.
3D models for those missiles.
3D models for the objects the player will be shooting at.
An explosion effect for when objects are shot.
Sound effects & background music.
Logic to handle the start and end of the game, along with the 60 second timer.
Logic to handle the scoring.
Logic to handle the actual “shooting” of objects

Here I’ve laid out all the features we’re going to add in the game, before I launch into actually how to do it.

Code

You can judge on a case-by-case basis how low-level to go with code examples and walkthroughs. If you’ve told them already that they need to know Node, there’s no need to explain any Node concepts, but if there’s a particular npm module they need, definitely include that as a step.

Break down code and explain it in plain language where appropriate — wherever you think your readers may need help understanding or where you want to give particular emphasis, spend some time making it as clear as possible.

Include code snippets as needed, but for large pieces of code, reference a GitHub repo or something similar instead; it’s always good practice to have your tutorial code somewhere available online for people to download and play around with.

If writing on Medium, if you hit the ` button on your keyboard 3 times, you can enter code like this:

let scene = SCNScene(named: "art.scnassets/ship.scn")!

Or you can use GitHub Gist — where you can write code, then use the Share button to get a URL — copy this into your Medium post and you should see something like this:

Thanks to this post for explaining that simply to me!

Story Structure & Content

If it’s not a tutorial, but more of a opinion piece, treat it like you were told in school — a beginning, middle and end. Imagine you’re telling someone a story about something and you want to keep their interest.

Some common sense tips:

Try not to meander or head off in tangents, or the reader may lose interest.
Don’t have too-long paragraphs or sentences.
If a picture or diagram would help, add one in. Like the main image, make sure you know what the usage license is.
Where possible give real world examples, to backup your points — like my samples from previous posts above.
Unless it’s something like a really well researched piece and you have lots of great content, don’t make it too long. This goes for tutorials aswell — I wrote a tutorial on how to make an AR game, but I split it into 5 separate posts as there’s just too much to go through in one sitting.
Spelling and grammar — obvious, but make sure you use a checker, and proof read it a few times before publishing.
Reading it out loud is a great way to spot mistakes, or to spot if your prose has gotten too long or just doesn’t make sense. If you’re proofreading by just reading, you may end up skipping over words without realising. Making yourself read it out loud will make it more likely that you’ll read it all.

And some pitfalls to just avoid:

Don’t be overly negative if it’s not warranted — it’s not Twitter.
Don’t name and shame people, unless you want to be sued!
Don’t lie! Medium is full of “real life experience” stories that are absolutely complete fiction. If you want to write fiction, then write fiction, but don’t lie to get views!
Don’t write or show anything inappropriate.

Ending

Make sure you wrap things up at the end — if technical, give links to your code if you have it available somewhere; if opinion based, make your conclusion and invite comments.

Some examples

This tutorial of mine has over 100k views currently, people love their segues:

Move between View Controllers with Segues — iOS #9

Creating new View Controllers (aka screens) in an app and moving between them is core to building apps. This post will…

appsandbiscuits.com

Here’s one about making Alexa Skills, admittedly with not the best image, but a good title!

How to make a custom Amazon Alexa Skill on your lunchbreak

The Echo is Amazon’s personal device that has been selling millions of units. Not available yet officially in Ireland…

lemarquisofandy.medium.com

A more opinion related one, which was my first blog post to really do well, with a nice image and title:

The engineer’s guide to not making your app look awful

A problem that a lot of independent app developers face is that they aren’t graphic designers. I work with an…