Tips on How to Write Your First Successful Technical Blog

What you need to know to get started

Hannah Pratte
Feb 20 · 9 min read

Introduction

If you have never written a technical blog before, it can seem a bit overwhelming. You might even be asking yourself, “Where do I even start?” If you find yourself in this position, the point of this blog is to help break down the whole process into something a little more easily digestible. Once you know some of the fundamental building blocks, the actual writing process will be a lot easier. But before diving into how to create a blog, I will briefly discuss why you should write one.

Why You Should Write a Technical Blog

There are many benefits to writing a technical blog and not only for the sole purpose of helping others. If you’re still on the fence, then here are five reasons why you should seriously consider creating one.


Idea

The first step is figuring out what it is you are going to be writing about. Think about all the past or recent projects you have worked on. Was there a time where you came across a difficult problem that you were unsure about how to handle and solve, but eventually figured out? If so, then this would be a great opportunity for you to share this bit of knowledge by writing an informative blog on how you went about solving that issue.

Usually, 9 times out of 10, if you have come across a problem, then someone else has too, so why not impart some of that useful knowledge to others?

Research

As with anything you will be sharing, you will need to do some groundwork ahead of time. Go on Google to look up what research has already been done on the subject you are wanting to address. Go to websites that you visited in the past and pull what you need. Doing this is not cheating, in fact, you are saving yourself precious time going this route. Why waste energy when someone else has done a lot of the initial work? All you are doing is collecting those useful pieces of information and consolidating them into one, easy resource for an individual to extract from.

Good artists borrow, great artists steal— Pablo Picasso

From there you can put that information that you have collected into a Google doc or Evernote if you choose. When you are ready to write your blog, you can easily go back and reference those notes.

Medium can also provide a plethora of useful how-to blogs, so check out what has already been written on your topic of interest. This can be a great resource to explore, in regard to blog formatting. When I first started writing blogs I actually went through a lot of different ones related to my field and studied the various structures, cover photos, common topics, and writing styles. To get an idea of whether or not a blog was received well by the public, I would pay attention to how many claps it got and if there were any consistent correlations. Once you find a consistent pattern, try to mimic it and see what happens.

Overall Structure of a Blog Post

Blog Title

You should create a title that is going to get straight to the point and capture your reader’s attention right off the bat. After all, this is one of the first things they will be looking at when searching for information related to their problem.

Most readers prefer Numbers in titles since our brains are geared towards thinking of things in a logical manner. For example, a blog titled “5 Hacks to Help you Succeed as a Developer” will tend to get way more engagement.

Including You in your title will also get more viewer recognition. When you address your reader, it feels more personal and as if you are actually talking to them.

Starting your title with How-to is also a great way to appear well in Google’s search. A lot of people tend to type “How” into Google when looking for an explanation, so including this is another useful tip.

Based on research from Conductor:

A good article to visit that will help you determine what a good title consists of is Sprout Social’s, 7 Headline Writing Tips That Get Clicks.

Cover Photo

A good cover photo is just as important as the title of your blog. It should be clean, have a good quality image, and match your topic. Some sites with high-quality stock photos that I tend to hit up frequently are Unsplash, Pixabay, and Pexels.

If you have an in-house design team at your disposal, then ask one of them if they would have some time to help you create a cover photo for your blog. Usually, they can get this done for you in a reasonable amount of time, but I would suggest giving them at least a week’s notice.

Introduction

After you create the title, you will need to establish a brief introduction as to what the majority of the blog will be about. This part does not need to be super long, but just enough to give the reader a bit of a synopsis of the topic. You could even briefly discuss how the problem came about or what inspired you to write the blog. Most of the blogs I read tend to have introductions of no more than a few sentences in length.

The Body of the Blog

This will be where the real meat of your content is contained and where people will be taking the most time on. Here are a few things you should be aware of and what your reader will appreciate.

Images

Whenever possible, make sure you use images to convey your meaning. Sometimes words will not do enough justice, and it will be a lot easier for your reader to understand at a glance. This will especially be important if you are trying to show someone how to write a particular codebase.

For instance, if you are wanting to demonstrate your code, just insert it into a text box like below.

class CreateOrders < ActiveRecord::Migration[5.2]
def change
create_table :orders do |t|
t.date :created_at
t.decimal :total
t.integer :order_status
t.timestamps
end
end
end

Images can also help break up what might seem like an endless sea of words. Some blogs, especially ones that are longer than 10 mins., would benefit from adding an image. This helps give your reader’s eye a break.

Short and Concise

Technical blogs do not need to be very long. Actually, the shorter the blog the better. You want to convey your point in as straight forward of a manner as possible. Write with the idea that someone will be able to skim and grasp what they need from the provided content.

A great analogy is to think about when people read the news. It’s early in the morning while they are probably drinking their cup of coffee or having a quick bite to eat before starting their day. Once that cup of coffee or breakfast is finished, then that’s it, off to work! So, think of the structure of your blog in that way, where you are trying to quickly give your reader what they need in a short period, so they can begin working on the problem.

Using Links

Rather than write out a whole separate explanation to something that ties into what you are talking about or backs it up, it’s best to insert a link. That way, your reader if they already understand or have heard of it before, can quickly move on.

However, there is such a thing as using too many, so just be judicious and ask yourself if it’s really necessary. There have been times where I have read an article, and there was a link on almost every single topic and subtopic. I would avoid doing this as it can end up sending your reader down a rabbit hole, which will affect how long your reader will stay on your page and finish your blog.

Write as If You Are Talking to a High-Schooler

This is not a British novel and there is no need for extravagant language. Save the Jane Austen and Leo Tolstoy writing style for another day for when you are going to be writing something in that form.

The point of this technical blog is to make it easy for anyone to understand and grasp the concept with as little effort as possible. Think about when you last read a newspaper or an online article. Yes, I know I keep referring back to the whole newspaper idea, but it does provide an excellent example as to how you should write a technical blog. In the article you read, you might have noticed that they didn’t use any fancy or over the top writing. The reason being was because they wanted everyone to be able to comprehend, and that is exactly the type of writing style you should replicate.

Remember, the simpler your language, the better!

Conclusion

This is what I call the final goodbye part of your blog. It’s where you will summarize everything that you have talked about to your reader. I would suggest keeping this part to about 3–5 sentences in length. It’s just a nice way to wrap up a blog and will feel less like you left your reader just hanging there at the end.


Editing

Now that you have finally accomplished writing your blog, the fun part begins, editing! Re-read your work and check to make sure everything is sound from a technical standpoint and on the grammatical side of things. Next, send it off to 2–3 people for any additional feedback that they might suggest. You can send it to a friend, co-worker, or family member, usually, people are more than willing to give helpful recommendations on how to improve your blog. It might be a bit nerve-racking to have someone else critique your work, however, it’s far better to get their opinion before sending it out into the world.


There you have it, a few simple steps to help get you going in the right direction when drafting your first publication. Hopefully, there is something useful you can take away from this when you set out to write your tech blog. Don’t worry about your first one being absolutely perfect, as with anything new, practice makes perfect.

Good luck!


As ever, QuarkWorks is available to help with any software application project — web, mobile, and more! If you are interested in our services you can check out our website. We would love to answer any questions you have! Just reach out to us on our Twitter, Facebook, or LinkedIn.

QuarkWorks, Inc.

Build better software.

More From Medium

More from QuarkWorks, Inc.

More from QuarkWorks, Inc.

More from QuarkWorks, Inc.

Ruby on Rails: Active Record Enum

More from QuarkWorks, Inc.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade