On Writing Tech Blog Posts

Posted by

One of my favourite bloggers, Steve Gordon, recently published an article that dives into the reasons you’ll become a better developer through blogging. As someone who’s been writing regularly for the past three years, his article struck home for me, and I encourage you to read it if you’re unconvinced.

Many developers start a blog, but then go long periods without publishing a single article, or give up on it entirely. In fact, for the longest time, I thought this might happen to me. Between full time work and raising a small child, my free time is limited. That’s why I developed a process to keep me on track, so that I can focus on other things, like spending time with my son.

The process is there to make things easier. It guides me from idea generation to draft to publishing. It isn’t difficult to put in place and it’s invaluable when motivation and free time vary. Steve’s article is the why — now let’s look at the how.

Quarterly Topic Brainstorming

The best place to start a blog post is not from a blank page. Once a quarter, I take a few steps back to create a backlog of topics that I’d like to explore in the coming months.

It takes less than an hour to get the ideas out of my brain and onto persistent storage, but it probably saves me hours of hemming and hawing over what I should write about.

Step 1 – Mind Mapping

I don’t even need a computer for this one. I grab a pen, a bunch of Post-it notes, and head somewhere to focus for thirthy minutes uninterrupted. The hardest part of blogging is choosing what to write about, so having a prepared list of topics in front of you lowers the risk of idea-hopping.

Each blog post gets its own Post-it note. I don’t filter my thought process at this point; I write down everything that comes to mind, no matter how crazy it sounds.

Not sure where to start? Choose a topic you’re already familiar with and go from there. Subjects you already well know are perfect when you’re starting out — they let you focus on the writing, rather than the technical details. It’s also a huge time saver to not spend hours researching the topic first.

At the end of the brainstorming session, I usually have Post-its strewn around all over the place. Time to neaten that up.

Step 2 – Group & Trim

Some broad categories emerge naturally even if you don’t have a theme in mind when brainstorming. I group those topics together, and give each category a name. It’s easier to choose a category first, and then a specific topic. It also makes it possible to see posts that build upon each other to be transformed into a multi-post series.

There will inevitably be some outlier topics that don’t fit in any category. These topics come in handy when you don’t feel like writing about what you’d originally planned. They’re useful to get out of a funk, and provide a nice change of pace. This blog post is in fact one of those — I’d been thinking of writing it for months now.

I transfer the final list of categorized topics into a Trello board. I’d prefer to keep them in Post-it form, but I don’t have the space for it. Besides, my son would surely find it irresistable to move the little yellow notes all over the house, turning my neatly categorized blog topics into a jumbled mess.

Here’s what my board looks like right now:

That’s it. I’ve now got a list of blog posts that covers me for months to come.

Step 3 – Writing & Publishing Schedule

The single best trick to regular blogging is to commit to a publishing schedule, and then figure out how much time you need to meet that goal.

For the past year, I’ve published two posts per month, but for a short while in 2019 that number was three per month. Two posts per month strikes a nice balance between achievable and over-committed. There’s nothing wrong with starting at one post per month either. Do whatever feels right to you.

Everyone is different when it comes to writing habits. Some are more effective first thing in the morning, before the rest of the family gets up, while others achieve more by staying up well past everyone’s bedtime. You’ll need to experiment to see what works best for you. Regardless of when I’m writing, I allocate 3-4 hours to complete a 1,500 word post.

I always have a backlog of two to three near-completed posts to have some leeway when something comes up. What happens most often in my case is a sick kid who needs a bit of extra TLC. All my other responsibilities get backed up, and I end up with less time than expected to write.

Writing A Post

Step 1 – Topic Brainstorming

This might be the hardest part of the entire process: picking a single topic and sticking to it to completion. My mood often affects what I choose. I’m more likely to pick a topic that is straightforward when I’m feeling tired. On the other hand, if I’m feeling adventuresome, I might pick a harder topic. Ultimately, writing a difficult post is more rewarding once it’s done.

With a topic in hand, I grab more Post-its, and take thirty minutes to brainstorm everything I want to mention in the post.

Step 2 – Outline

The next step is to organize the Post-its into a coherent outline that will form the backbone of the article.

Once my thoughts are organized, I fire up my editor (WordPress) and jot down the outline into a new post. I add a bit more detail about each point so that I have a firm idea of what I’m going to say in the first draft.

Here’s an example of what the outline typically looks like. I haven’t quite finished it, but you get the idea:

Err on the side of including more than you need in the post. It’s much easier to remove content from a long post than it is to add to a short one. Don’t make the post longer than it needs to be, but also don’t leave anything relevant out of it.

Step 3 – The Draft

It’s time to start writing some actual sentences! Don’t focus too much on dotting the i’s and crossing the t’s yet. The goal of the draft is to get all the information out of your brain and onto the screen. A few gramatical errors aren’t that big of a deal at this point.

I use a placeholder for code references and diagrams rather than including them right now. It’s best to stay focused on writing the draft first. Similarly, I use a unique string of characters that I wouldn’t use in a normal sentence when something needs to be fact checked. It looks something like this:

You can write a function in one of seven <mrv> different languages.

During final preparation, I’ll go through all the placeholders and validate that what I said is correct.

Step 4 – Editing

Once the first draft is done, I step away for a day or two before refining what I wrote. That little bit of time makes me feel less attached to what I originally wrote, and more likely to see where I need to trim, clean up, or add more detail.

The primary goal of the editing phase is to transform the draft into something that can be easily understood by your audience. I do editing in three steps:

  1. An on-screen edit to remove obvious grammatical errors and improve the clarity of my sentences.
  2. A second edit with a printed version of the article. It’s easier to reason about the article as a whole when you can see it all in front of you at once.
  3. Optionally, a final edit by a friend, colleague, or family member. Ideally, that person has some knowledge of the topic at hand, but it could be anyone, from your spouse, a friend, or even your mom!

Step 5 – Final Prep

The hardest part is done. It’s time to find some relevant cover art, write excerpts, insert any code or diagrams, and prepare any messaging for social media. I always reward myself when completing a blog post, even if it is just taking a few minutes to get some fresh air.

Finally, I’ll schedule the post to go live at the busiest time of the day for my blog, as determined by Google Analytics. I’ve heard that it’s worth re-posting the same article multiple times to social media, since not everyone is checking their feeds at the same time. I haven’t experimented with that approach yet.

Rinse & Repeat

I hope that if you’re still with me, that you’ve picked up some tips to improve your own blogging. It’s not that complicated, but there is a non-negligable amount of work that needs to be put in to each post to create something of quality.

Did you find the information you were looking for? Is there something missing from this article that would make it more useful to you? Do you have a follow-up question? Feel free to reach out to me on Twitter or LinkedIn. I’d be glad to help out.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s