How to Write an Awesome Technical “How-To” Blog Post

Photo by Adri V

Over the past few weeks, I’ve been coaching my teammates and mentees on writing technical blog posts. For many of them, writing technical blog posts is new to them, so there’s usually a big learning curve involved. It’s not only about conveying a complex technical topic in a succinct manner. It’s also about the authors finding their writing voice.

I actively encourage all of my teammates to blog. I also make it a part of their jobs, and not some extra-curricular thing. I think that blogging is a great way for tech folks to build their personal brand, develop leadership skills (no better way to demonstrate leadership than to communicate effectively), and to give back to the tech community. As tech folks, we all rely heavily on blog posts (and StackOverflow!) to get our jobs done. It’s always nice to be able to pay it forward by sharing it with the world when we figure out how to do something that was gnawing at us for weeks. On a more selfish note, it’s also a great way to do a brain dump. It has the added benefit of giving your brain room to learn new stuff, and also serves as a great reference for yourself. I can’t tell you how many times I’ve gone back to my own technical articles to look things up.

This week, while helping out one of my teammates with his technical blog post, he said to me, “If you wrote a blog post on how to write a technical blog post, I would definitely read it.” 💡 Heeeey….not a bad idea! What a great opportunity to not only help my teammates write better blog posts, but to also share my experience and learnings with others.

Showtime!

I highly recommend following all of the points below when writing a technical how-to tutorial-style post, in order to ensure maximum effectiveness. As an author, you goal is to convey a complex technical concept in an easily-understandable manner. You want to make sure that your readers come out feeling like they learned something useful and/or that you helped them solve a gnarly problem.

Note: This article is aimed at folks who are writing a technical how-to tutorial-style post, which involves detailed code examples and explanations. You can use many of the concepts covered here for technical non-how-to posts as well.

So…without further ado, behold…my tips on writing a kick-ass technical blog post!

Your title should be descriptive enough to signal to the reader what to expect. While it may be fun to come up with a witty or catchy title, that won’t get you found on Google or some other search engine.

The picture doesn’t have to be related to your post. You can find tons of cool royalty-free photos on unsplash.com. Just make sure you attribute the photographer. I often use my own personal photos for my posts. For your own photos, attribute yourself as the photographer. Do whatever tickles your fancy, but include a photo.

Nothing sucks more than a boring opener for a blog post. Start with a fun personal story, or a scenario. Beware of having a long opener — if you beat around the bush too much with your intro, your reader may lose interest.

What are you trying to accomplish with your post? Who is this post aimed at?Make it super clear, so that the reader knows what to expect. It also helps to keep you in check too!

Know your audience! When writing a technical post, you can’t be everything to everyone. If you’re writing a more advanced technical post about Kubernetes on GCP, for example, state that you’re assuming that the reader is familiar with setting up Kubernetes on GCP.

When writing a technical post, especially a tutorial, it’s super important to list what tools are needed to run the tutorial. If possible, include commands for installing certain tools, or provide links to the tool site’s installation instructions. Don’t forget to indicate what version of the tool(s) you’re using.

Sometimes it’s helpful to provide recaps of certain terms in your post, to avoid having your readers go back-and-forth between your post and Google to define a key term. For example, when writing a technical how-to post on OpenTelemetry, consider including a quick definition of Observability and OpenTelemetry.

You’re writing a technical blog post. You need details. If that means that you end up with a 10- or 15-minute read, then so be it. The key is to make sure that you are clear and concise, while providing enough detail for your readers.

While I am giving you permission to write a long post to convey your point, what I do advise against is trying to cover too many different things in a post. Make sure that the post is laser-focused. It’s fine to do an overview of core concepts and terminology, but if you find yourself meandering into another topic, then STOP, and ask yourself what you’re trying to accomplish with the post.

Photo by Adri V

Just because a post is long doesn’t mean it should be one big wall of text. Include diagrams (where applicable), photos from Unsplash, your own photos, or fun animated gifs (e.g. from giphy.com) to break up the text a bit. If you’re including diagrams or images, always provide attribution in the caption, whether it’s from an external source, or it’s something that you created yourself. Careful not to sprinkle too many memes or animated gifs in your post, otherwise it starts to look tacky.

I absolutely hate reading technical posts where it’s clear that the author got bored halfway through, got lazy, and decided that it wasn’t worth the time and effort to explain a concept in detail, instead leaving it to the reader to figure out what in Space they’re talking about. It’s irritating, and if you’re new to a particular technology or concept, it can be deflating.

So, when you’re writing a technical post, make sure that you include the following:

  • Code snippets. When writing a technical how-to tutorial-style post, it is important to include code snippets. Be sure to explain what the code does, and call out specific lines of code that highlight a point that you’re trying to make. If the code has variables or parameters, explain what these are. If you’re writing on Medium, you can do this by embedding GitHub Gists.
  • A sample git repo. Yes, it’s a pain in the buttocks to set up an example repo (almost as much work as writing the tech post itself), but it’s soooo worth it! Whether you host your code on GitHub, GitLab, Bitbucket, or wherever, it doesn’t matter. Having an end-to-end working example that readers can clone and try on their own is super-duper handy. Having blog posts with example code repos has saved my hide tons of times.
  • Versions of the things that you’re using! If you’re using a tool, framework, programming language, etc., be sure to explicitly indicate what version you’re using. I can’t tell you how many times I’ve tried following a coding example, only to find out that the version of the tool in the example was older than the version I was using, resulting things not working because in version 1.2 of a framework, there was a field called get_cats, and in version 1.3, the field was renamed getCats.
  • Sample output. If you’re giving an example of a command, show some sample output so that your reader knows what to expect when they run that command.
  • Gotchas. It’s likely that you’ve run into issues when trying out a new technology. When blogging about it, share some of the issues you ran into. Chances are, your readers may have encountered the same thing. It may also save them from archaeological digs through Stack Overflow.
  • Define key terms and avoid lame-o definitions. I hate it when I’m reading a blog post whereby the author defines a term, and it’s clearly swiped from Wikipedia or user docs or whatever. To me it shows that they don’t fully understand the term, and are just parroting a definition. Make an effort to understand key terms/concepts that you’re blogging about, by providing definitions that are easy to understand. Include examples if possible.

Just because you’re done writing, it doesn’t mean that the post is ready to be published. I always give my posts a read (sometimes multiple reads) after I finish writing them. It’s best to re-read your post the next day, or even a couple of days later, to give your brain a break from the post.

As part of your editing process, you may have to re-arrange sections, or scrap whole sections altogether. It can sometimes be heart-wrenching to do so, especially if you need to delete a section that had a kick-ass paragraph or sentence. Never fall in love with your writing. Be prepared to let it go for the greater good.

Also be prepared for the fact that you may very well spend as much time editing your piece as you did writing it.

I never publish a blog post without having at least one other person review it. If it’s a super-duper technical post, I usually try to get 1–2 people with expertise in that area to review, to make sure that I’m not spewing hooey in my posts. If I’m writing an intro post, I also try to get someone who is technical, but who isn’t familiar with the topic I’m writing about, to read the post, so that I can gauge whether or not I’ve got the right level of detail in there.

Just because you publish a post doesn’t mean it’s set in stone. I’ve found myself tweaking a post days, weeks, or even months after publishing. My goal is to ensure that my posts are clear and accurate. Sometimes I’ll get a comment or question from a reader on a topic that I thought I covered in enough detail in the post. After re-reading the section in question, I may decide that it requires further clarification, in which case I’ll revise the section to add clarity. Don’t be afraid to go in and revise your post to clarify things. I see technical blog posts as living documents.

Don’t just end a post. That sucks, and gives your reader no closure. I love closure. 😊

Your conclusion should summarize what you’ve covered in your post. I like including bullet points to capture the main things that I’ve talked about.

If you used a bunch of resources to research your post, include them. It’s super handy to folks who might be in the same boat. References to include:

  • Blog posts you relied on for your research
  • Links to StackOverflow posts that you encountered as part of your research
  • Cool books or articles to check out on your chosen topic

If you’re on social media, MILK IT, my friend! Post links to your article on LinkedIn, Twitter, Facebook, and Instagram (if applicable). Share with your friends. Ask your tech friends and co-workers to show their support by following you and by liking your posts.

Photo by Adri V

Conclusion

Writing a technical how-to blog post doesn’t have to be rocket science. Just stick with the above rules, and you’ll be writing kick-ass blog posts in no time! Key takeaways:

  • Include a descriptive title, and an attention-grabbing opener with an eye-catching pic.
  • Clearly state your objectives, assumptions, and prerequisites.
  • Be nauseatingly detailed (code examples, definitions, screen outputs). Nothing sucks more than a technical post where the author gets lazy partway through. It shows.
  • Edit the heck out of your post, and ask a friend (or more) to review to validate flow and technical accuracy.
  • Break up the wall of text with fun pictures and relevant diagrams.
  • Promote your post on social media so that it gets seen!

So, my friend…you are now ready to write your very own technical post. Go forth and spread tech bloggy goodness!

Now, please enjoy this photo of a yak chillin’ in the mountains.

Photo by Sanjay Hona on Unsplash

Peace, love and code.

I push the boundaries of software delivery by learning from smart people who challenge the status quo. Former corporate automaton.