How to write a (technical) blog post

Survival Guide


Story by
Dinko Gredelj

If you decide to write a technical or professional blog for the first time, it might seem scary or even paralyzing! Therefore, I want to share a short survival guide that will ease your pain. Before I introduce some technical guidelines and recommend a structure, I want to explain the purpose, motivation and usefulness behind blogging.

Some six months ago, we started with blog posting in t-matix. It wasn’t easy at the beginning, but after some time, we started blogging more often and with more confidence. Our recent authors have told me about their experiences and obstacles that they encountered when they began to work on their blog posts.

Antonija wrote our first blog post ever. She made a summary of how we use Zoookeper – a centralized service for maintaining configuration information, naming, providing distributed synchronization and group services.

The biggest problem I had while writing was encountering too many unknown, technical words about Zookeeper, of which I didn’t have a deep understanding. With my Mentor’s help, I learned a lot about the topic and managed to finish the blog post.” 

Antonija Samaržija, Back End Developer

She admits that it was very cool to see her blog published online: “Some colleagues approached me to tell me they liked it,” recalls Antonija.

Zookeeper is maybe not the most popular software development buzz word, but Kubernetes for sure is. Goran covered the topic in his blog post. “I chose Kubernetes, as this was one significant migration from the old servers, and a way of thinking towards a new one as well as a fresh platform. It was a big achievement that we did this in only six months,” says Goran. He doesn’t believe that people were reading his blog to try and understand Kubernetes:

“They wanted to hear the ‘war story’ of what we went through, and it might have served as an incentive of why use Kubernetes and why not.

Goran Pizent, Head of Infrastructure

Also, he noted that if his responsibilities allowed, he would write blog posts more often. “I like to share the knowledge that I have and show things we do in Infrastructure, which are often invisible,” says Goran.

One more blog didn’t slip under the radar of our readers. Dražen used some of his back-end knowledge to bring us the most read blog post until now.

People start writing blogs once they know enough about a topic and they want to share with others how to use something and why it is cool or not cool, or how to get the best out of something they know.”

Dražen Bandić, Back End Developer

With no prior experience in writing blog posts, it took him 4-5 days to prepare a blog post named Apache Kafka as a Middleware in a Microservice Infrastructure. Even though he claims that someone with more experience in blogging would work the subject faster, he encourages you not to give up: “When you’re writing your first blog, you need to be patient. It might not be the greatest, but keep going!”

If I already managed to convince you that blogging is not a tedious and challenging task, and you can get down to it with no previous experience, do not stop reading this post. Now I introduce the Survival Guide that will help you write a high-quality blog that is sure to become a popular read.

The Survival Guide

You’re in the middle of your everyday work, and suddenly you discover something cool which you think would be nice to share with the world. Soon enough, someone suggests that the topic would make an excellent blog post. Your first reaction might be:

  • Why do I have to write this blog thing?

Before asking yourself this, consider the benefits:

  • It helps you show your expertise and improve your professional profile.

  • It helps your colleagues and team understand the processes or tools you’re using, without your having to force ‘your way’ onto them.

  • It helps the company attract new customers and employees.

  • It helps with internal and global knowledge sharing processes in a specific community.

You might also have some common misconceptions:

  • I’m not good at writing.

  • Your 5th article will likely be five times better than your first one. Practice makes perfect!

  • Other people do it so much better.

  • Those great writers also wrote their first article once. And they were probably not too happy with it, either.

  • I’m not an expert in this field.

  • We always tend to underestimate our knowledge and take it for granted.

  • It’s a boring topic.

  • There will always be greater experts, but you will bring new information to most of your audience.

  • People who are interested will read it, and those that aren’t won’t even look for it or open it.

  • Your audience is wider than you think.

  • Consider how many tutorials you’ll find on silly subjects on YouTube – how many times have you resorted to them when trying to solve a specific problem?

  • Focus on your interests rather than expertise. It’s so much easier to write about things that are close to your heart than those that are your everyday work necessity. Even if you know less on a topic that interests you, it will be much more fun to both write and read.

  • Every professional blog must be very formal.

  • It’s perfectly ok to add a bit of your personality and character to your writing. People enjoy this more than ‘dry’ texts.

  • Go easy on the humor – it’s a slippery slope as not everyone enjoys it while reading a blog.

How should you start:

  • Just get started – don’t overthink it.

  • It’s easy to change or fix something later on when your thought flow becomes clearer.
  • Write down ideas that appear to you from:

  • a project
  • a colleague
  • a conference topic
  • a problem you’ve solved.
  • Read a few blogs from a similar industry.

  • Tell it to yourself as a story. You know this story very well. Try recording it as an audio.

  • Listen to the audio file and pull out the key bullet points.
  • These bullet points are now the key talking points of your blog. Are they in the correct order?
  • Add some content to these key points.
  • Write it in a way that you would like it explained to you (i.e. technical for tech people).
  • Use a real case study:

  • What was my problem?
  • How did I solve it?
  • Show actual data.
  • Don’t worry about formatting or typos!

  • Just let the text flow if you get an inspiration.
  • You can make it pretty later, or maybe someone can even help you with that.

Recommended Structure

Let’s assume that by now you’ve already put some words on paper or screen. Your next step would be giving it a structure that the typical reader will recognize and follow with no problem.

  • Headline/Title

Avoid complicated titles, and instead try to define what the reader will find inside: “How to…”, “Introduction to…”, “…by using tool XYZ”, etc.

  • Quick summary

Readers appreciate having this section as it quickly helps them decide whether this post is relevant to them or not. Try to summarize the entire blog in a few sentences or talking points.

  • Introduction

This part should be used to allow readers to ease into the topic without going into heavily technical details. This is where you provide any necessary background for a better understanding later on.

Image 1. Locust- a Hidden Gem in Load Testing, a blog introduction screenshot
  • Break it down into parts

It’s easier both for you and your readers if you break down a big topic into systematic pieces that are easy to follow. This is particularly important if you’re writing a technical guide. Then, besides breaking it down into parts, ensure that each piece is very detailed, as people come with different knowledge levels and experiences and might not understand a step that seems logical to you.

  • Examples

Examples are not just optional but are in fact considered the key value of a blog. People will often jump directly to examples to see if they relate to their problem. However, for a more careful reader, it’s also essential to ramp up the complexity of the examples – a smooth learning curve helps people jump on board at the point where their problem or knowledge gap starts.

Image 2. PostgreSQL as a Time Series Database, timescale table creation screenshot
  • Summary

Here you can sum up the knowledge gained or information absorbed by reading the blog. This is the part where you can also suggest further reads on the topic, write a quick thank you to anyone that helped, and if you wish, include information for readers to contact you.

Technical Guidelines

These things are often overlooked, but it doesn’t mean that that’s what you should do…

  • Summary

This is something you should agree on with the person requesting the blog, but keep in mind that a concise article might be dismissed as useless, while a very long one might scare away a certain number of people (which I’m risking here!).

  • Reference used material

If you’re quoting an author or entire article, it’s nice to give credit to them, but it also helps the readers to find more information on the topic if they find it interesting. The same logic applies to providing the location of any graphics you use.

  • Phrasing1 and language

Know your audience – this helps you phrase your blog in the terminology adequate for a specific group of people.

  • Keep it simple

Just because it’s a technical blog, it doesn’t mean it can’t be simple. Avoid complex phrasing or indirect language.
Also, avoid internal lingo:

  • People won’t recognize the names referring to internal tools or processes.
  • People might mistake acronyms for something else – did you know that ‘DSL’ is an acronym with at least 68 different meanings?
  • Think about the visuals

People will enjoy a few pictures or graphics as they will make the text easier to understand. Write well-rounded paragraphs rather than a single block of text, and separate sections in a way that’s easy to follow.

Wrap up

After reading my post, you’ll hopefully have a better idea of how to start a blog of your own. But since this was my first attempt at such a task, it might be wise to check out the experts on the topic, who gave me some ideas on how to put this together:

If you’re still not sure how to start, have a look at our Dev Corner.

My colleagues are doing a great job there – in much the same way as they are in Development.

Other blogs

PLATFORM
December 18, 2019
Continuosly building, testing, releasing and monitoring t-matix mobile apps

Story by
Josip Virovac

PLATFORM
November 5, 2019
Kubernetes-what is it? And how do we use it?


Story by
GORAN PIZENT

PLATFORM
September 25, 2019
Locust- a Hidden Gem in Load Testing


Story by
Igor Crnković

View all
2020-02-25T11:38:44+01:00