Tips for Writing Technical Blog Posts

As a developer one of the best ways of giving back, beyond releasing code, is by writing about your experiences. Think about all the people you follow on social media. Chances are you follow the ones that are sharing knowledge and inspire you.

I love this part of the industry but a lot of times I see developers make common copywriting mistakes in their blog posts.

What good is a tutorial or article if it’s glanced over or never found?

In this post I’m going to outline some of the tips I’ve picked up and mistakes I’ve made in the past.

Article Structure

Your technical blog post needs structure. Two common methods are:

• Introduction, body, and closing.
• Pain, dream, fix (by Amy Hoy)

The first method is what a lot of technical articles use. It has a tendency to come out pretty dry and boring.

I like the second method better as it makes it easier for you to set up a story. The basics is to start your article by focusing on the pain or problem, then a dream of what you want to accomplish, and finally the actual fix or solution.

As a developer this is much of our entire day, so moving it into a story form is easy and should come naturally.

Article Title

Have you spent hours crafting a blog post, editing it, making sure its perfect, only to have it be a big flop? I have, numerous times and one of the common problems is the title. In fact much has been written about crafting the perfect title and it could be argued it’s the most important part of your article.

For us developers the best titles are those that other developers will be searching for. For example on my site “Switching to PhpStorm” and “Setting up Gulp, Bower, Bootstrap Sass, & FontAwesome” are my most popular posts. The only reason is because they appear in search engines.

Those two posts I threw together fairly quick and the ones I’ve spent the most time on hardly get any traffic.

Article Introduction

I touched on the introduction previously but it needs it’s own section. The introduction is the second most important part. This is where you inform readers on what to expect and set everything up.

I come across lots of articles where this is missing or just generic filler. It doesn’t draw me in and at that point I just scan the headings for sections that sound interesting.

Article Content

Including headings and scannable break points is another important feature. On the web readers quickly scan articles so you need a break to draw them into each section. Some examples are of course headings, blockquotes, lists, and images.

It’s also important to write clearly and keep your style consistent. In technical writing that means keeping your naming the same. A common example is writing the word JavaScript. Don’t mix between using js and JavaScript. Stick with one.

Another tip is to run your text through an app like hemingway. For web writing keep everything at a grade nine reading level or lower. Using small words helps readers where English isn’t their primary language, and makes your content more consumable.

Article Closing

In copywriting the closing is typically your call to action. Most developers aren’t selling anything so this is a great spot to ask for comments, connect via social media, or recap the article.

Wrap Up

I hope these tips on the structure, title, and content help you the next time you are writing a technical article. Now go and write about that problem you solved today. I’m sure it would be a benefit to others.