Fluxus Frequency

How I Hacked The Mainframe

How to Write a Technical Blog Post: Part 1

This post originally appeared on The Quick Left Blog

Part 1: Prepare

Content is king. Bill Gates predicted it in 1996. Much of the money made online today is in content. In the tech world, where languages and frameworks are here today and gone tomorrow, this is doubly true. Developers, managers, and CEOs of technical companies spend an enormous amount of time understanding their chosen tools, the next hot thing, and how to stay relevant.

It’s no wonder so many startups host blogs on their sites. Blogs drive traffic to your site, increase your visibility, and elevate your brand in the tech world. So how can you get a piece of the action?

In this three part series, we’ll explore some strategies you can use to generate ideas, produce clearly written blog posts, and effectively promote your work on the internet. In this, the first part of of the series, we’ll talk about how to get started as a technical writer: overcoming mental resistance, generating ideas, and starting with your audience in mind.

Get Psyched Up

Figuring out how to write a technical blog post can be overwhelming if you’re not used to it. Many people find it hard to choose a topic. A lot of times, it comes down to feeling like you don’t know enough about anything to write about it. But if you think that you have to be an expert before you start writing, think again.

I don’t know how many times I’ve heard people say: “I would write about (insert technology) if I knew a little bit more about it”. It’s common to feel uncomfortable with the idea of publishing a piece telling the world “how you should do X”. But fret not. This is just a little bit of imposter syndrome.

Try on a different perspective: think of blogging as a learning process. Maybe you’re not the world’s foremost expert on Flux. It interests you, but it’s a little bit hard to wrap your head around. Instead of feeling like you have to be an experienced Flux developer before write about it, think of it as the path you’ll use to understand it. There’s no better way to understand something deeply than to teach it.

If you want to learn something, read about it. If you want to understand something, write about it. If you want to master something, teach it.

- Yogi Bhajan

Blogging can be a great way to give structure to what you want to understand about a topic. It can also serve as a roadmap of how you will get to mastery. What are the components of the topic? How can you break it down? What little pieces can you try to grok that will help you see the big picture? These are the questions you have to ask when you’re teaching something. They also happen to be the questions you’ll need to answer to learn something!

You can also treat blogging as a way to document how to solve a specific problem so that you can look it up later. Once you’ve gone through the struggle of figuring out what’s going on, you’ll have a handy place to go back to and remind yourself what you did - in your own writing! Might as well open source it.

There have been a number of times in my blogging career when people have read one of my posts, then reached out to me and and asked: “you’re an expert on X, what can you tell me about this one arcane part of how its written?” In almost every case, it was the first time I’d even tried to understand the topic!


So you’ve gotten past your initial reservations about writing, it’s time to choose a topic. Figuring out what to write about can be just as daunting as deciding to write. But once you know where to look, you’ll find that fertile ideas present themselves every day.

Here are a few of the strategies I use to come up with topic ideas.

As a consultant, I work on a lot of different projects. Each one usually has one or two unusual problems that have to be solved in a novel way, either due to the business domain or idiosyncracies of the tech stack. I keep an eye out for things like this and write about them. They usually make for an interesting read for curious developers.

I also keep an eye out for ways that I am percieved to stand out by client teams. Sometimes I’ll suggest a certain way of doing things that is new to a team, and I get a lot of feedback about what a great idea it is. For example, the Quick Left Pull Request Template is often quite appreciated.

Similarly, the particular business situation that a client company finds itself often lends itself to a process-related post. I recently did some work for a company whose codebase hadn’t been worked on for a while, so I wrote this post and this post to help technical leaders in this situation find some direction.

In all of these examples, you could just as easily leverage your business or technical situation even if you’re not a consultant. Think about your codebase’s “gotchas”, ideas that new hires have brought in, and the quirks of your particular niche in the business world. These are rich sources of post topics.

If none of these situations applies and you’re still drawing a blank, you can always go the old fashioned route: google it. Sites like Buzzsumo, SEMRush, and Alexa are great for generating ideas. I also recommend Google Trends for figuring out what’s people are asking about a given topic. All of these tools are great ways to identify things to write about that people will actually be interested in reading. This great for generating page views.

Consider Your Audience

While we’re on the topic of page views, you should probably consider who it is that you’re writing for. Is it developers? Your product owner, scrum coach, or CEO? Maybe marketers or salespeople? What role do they play in the tech industry?

It’s vital to have an idea of who you want to read your post. Knowing this enables you to answer an important question: what problem(s) does this person need to solve in order to do his/her job?

When people face a difficulty that they don’t know how to solve, they google the answer. If your blog post comes up at the top of the search results, they’ll probably read it. On the other hand, some folks will look for the answers to their questions in other places online. Where does your target audience spend their time? Are they hanging out on Reddit, Stack Exchange, or Quora? Think about how you can get your post there, and write it such that it will be accepted by that online community.

Identify A Long-Tail Keyword

You might think that marketing your piece is something that comes after you’ve written it. But considering how you will promote your post before you write it can help focus your writing and lead to a warmer reception when you publish. One of the easiest wins you can make early on is to choose an effective title.

I typically try to match my titles with a well-chosen long tail keyword. Long tail keywords are specifically targeted 3-4 word phrases meant to be found by readers researching a particular topic.

Because single-word rankings in search results are very competitive, it’s easier to get a higher search result rank for a multi-word phrase than a single keyword. Usually, it’s best to think of the most compact way to express what you’re writing about using common language.

For example, the long-tail keyword for this post is “how to write a technical blog”. It’s more likely that someone would search for that phrase than something longer like “steps to follow when you want to publish your first technical blog post”. On the other side, it’s more likely that my audience will find my post than if I had used something more generic like “tech blogging”.

Generating a good long-tail keyword is a bit of a fine art. If you have any friends that are marketers, ask them for help. Barring that, you can google terms similar to your idea to see what people are asking about, use a thesaurus, or follow the suggestions in this article.

Wrapping Up

Getting into the head space of writing a blog post can be difficult at first. But when you treat it as a learning process and break the process up into small, manageable tasks, it becomes easier. In this post, we’ve looked at how to rethink your mindset about the purpose of blogging, ways to generate ideas, thinking about your audience, and how to drive your topic with a tightly focused long-tail keyword.

Stay tuned for part two of this series, where we’ll talk about another important aspect of how to write a technical blog post: improving your actual writing process itself. Until then, good luck and happy blogging!