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.
Create one or two paragraphs of a very quick summary of the complete article - maybe one or two sentences per definition. If they don’t understand the summary completely, they’ll know that it’s because they skipped the detailed explanation.
Another way to look at it is: Imagine that your reader is about to get to an important meeting and they need to sound like they know everything about your article, so you have 30 seconds to explain it to them; otherwise, they’re going to get fired!
7. Say goodbye
This, just like the body of the post, has to sound like you. This is where you get to be friendly and yourself. You can use one or two sentences to say goodbye and thank them for reading. You can even sign with your name or a nickname. I personally prefer to sign with “-Alex.”
Recap
Pick a title that will catch the reader’s attention. You can choose to explain exactly what the article is about, make a list of things, or create a catchy title. You can even add a question to the title to spark your audience’s curiosity.
Write an introduction to give the reader a better idea of the post’s topic. This is where they’ll decide if they want to read your content or not!
Write some definitions or pre-requisites, so your reader is not confused when they read the rest of the post. Depending on who the article is for (your target audience), you can give a quick 2-sentence summary, or you can redirect the reader to a previous article.
Develop the article! Remember to be yourself and try to keep it short, unless it’s a very technical post. You can also break it down into a series of articles instead of having one long post.
Add visual content to keep your reader’s attention, but don’t overdo it!
Write a conclusion or a summary. Remember to imagine that you have 30 seconds to summarize your article, or your colleague will get fired!
Say goodbye to the reader in your own special way.
I hope this was helpful to get you started on creating some blog posts!
Leave me a comment if you have any questions or if you’d like to see more content about writing technical articles.
Prost!
-Alex