7 tips to start writing your technical blog post
In the previous post, Things to consider before writing a technical blog post, we asked ourselves some questions to help us choose the topic that we want to write about. We also learned how to visualize our target audience before writing our post.
For this post, we will start writing our article or blog post! Yes, just like that. Take your laptop, your PC and your keyboard, your tablet, or whatever you’re most comfortable using. Just take it and follow these simple steps to start writing!
1. Pick a title
You can change this title later, but pick something that’ll keep you focused on what you’re trying to explain. This way, if you find yourself over-explaining something, just read your title once more and ask yourself if you actually need that long paragraph, or if you can keep it shorter since it’s not the focus of your article right now.
You can create a title that explains exactly what you will be talking about. Look at this example: “How to get started on Java programming.”
You can also create lists of something related to the technology you chose, for example:
“5 ways to improve your application’s performance”
“10 tips for improving your time management skills”
“5 reasons why you should be using Service Mesh”
“The 10 biggest mistakes when developing Python scripts”
“The 5 biggest misconceptions of RESTful APIs”
Some authors choose titles that are catchy or end with a question to grab the reader’s attention, like this one: Software Quality is not cheap, but would you risk your company’s future for the lack of it?
Ultimately, you want a title that will help your audience understand the topic of the post, but you also want something memorable.
2. Write an introduction
Most people will only read the first(s) paragraph(s) before they decide if your post is worth reading or not. The introduction can be just one or two paragraphs; try to keep it simple.
Write a summary of what you’re going to cover with your article and try to get the reader’s attention.
A popular way of ending an introduction is with one or two questions that you’re going to answer throughout the post, which will also pique the reader’s curiosity.
“Can this function be used with objects?”
“How can you achieve high performance with complex code?”
“Is it really worth using APIs for your project?”
3. Write some definitions or pre-requisites
This step is optional. It depends on what kind of audience is reading your post. I personally try to explain the basic concepts that the reader needs to know so that they can follow along with me.
How long the explanation is, depends on the definition’s complexity and how important it is for the audience to know this term before they read the rest of the post. Sometimes I use two or three sentences to define a term or concept. Sometimes I use one or two paragraphs. And sometimes, I even create a whole separate article to explain it, and then I just reference that post (with a link) before starting my current one.
4. Develop the article
Now you can start writing the actual article’s content. Explain all you want, or talk to the reader just as if you were face to face. Use formal or informal wording. In this part, try to be yourself! This is what will differentiate your post from others. Even if you write about a very well-known subject, maybe you’re using a new perspective that no one has done before, or maybe you’re giving easy-to-read explanations. This is your essence as a writer. Own it!
Make use of titles and subtitles, or bold and underlined formatting, in order to have a readable and user-friendly format. Structure your post in sections. If your audience has to pause reading the article for a meeting, when they return, they’ll easily want to know where to continue reading afterwards. Having subtitles or sections will help them maintain some order. Otherwise, they’ll get lost in between paragraphs and may lose interest in your post.
Note: people tend to read articles that are shorter (2-5 minutes, or 800-1,300 words), but sometimes posts can become longer when there are a lot of explanations involved. You can always separate your information in a series of posts (Part 1, Part 2…) instead of creating a huge article.
5. Add visual content
Most people nowadays want to read articles because they are way quicker than reading a book. We don’t have the time, nor the mind, to be able to sit for hours and read a programming language book. Instead, we read articles or watch videos that can easily break down the information.
For this same reason, the average reader today may lose interest if the post is only paragraphs with no visual content.
Adding media (pictures, gifs, pieces of code) will definitely get the reader’s attention, and people may focus on these visuals if they don’t want to read everything. Or the readers can skip the explanations because they can understand your post just by looking at the pictures or even the subtitles.
Be careful not to add a ton of media everywhere; doing this will also lose the reader’s attention because they can lose the sense of the section they’re in and feel lost. You do not want your target audience to feel lost while reading your article.
6. Write a conclusion or a summary
Some readers will skip your article altogether because they don’t feel like reading. It’s not your fault; that's just the way it is. So, be ready for your readers to skip the whole explanation.