The Structure of a Good Technical Article
September 20, 2020
One of the great things about Medium and any other blogging platform honestly, is that literally anyone can write and publish their content. And funny enough, one of the worst things about them is exactly that same thing.
Let me ask you this: do you find yourself often captured by the articles you read? Or do you normally skim through them trying to find what you’re looking for, ignoring all the extra mumble-jumble authors add to fill in the blank space? Just because anyone can write, doesn’t mean you have to like it. So, by leveraging my own experience writing technical articles (you can check my credentials here), in this one, I’m going to try and list the generic structure your technical articles should have in order to succeed at their purpose (which is to transmit information to readers).
There are no magic formulae to figure out the perfect structure, but trust me, I’ll try to get as close as possible here!
A Strong But Short Intro
Other than your article’s title, this is the first thing your reader will see and, well… read. So it needs to grab them by the chin and make them want to read the rest. In order to do that, you need to start by giving the reader a problem to solve. This is achieved by presenting the particular problematic that the topic you’re trying to impart solves. After all, they probably reached your article finding a solution to a similar problem, so this will help them connect to your message.
So, for instance, take this post, I’m trying to teach you how to structure a blog post, so my introduction talks about the difficulties of writing something that most people will want to read, it talks about how although there are no sure ways of doing it, this article will teach you how you can improve your odds.
That last part is key: after you present the problematic you also mention how the following section is going to help them solve them.
Now, although this is key to make people want to read your writing, also remember to keep it short and concise. You don’t want them to spend 10 minutes reading just your introduction, that will not solve their problems. If they need to spend that much time in order to understand how your article will help them, then they’ll get bored and find the information someplace else.
There is always time to expand on your original ideas down below, once you start covering the actual topic (see what I did there? That is exactly what I’m doing here… * wink * * wink* ). Which takes us to the next section: the body.
The Body of Your Article
Clearly, this is where the meat of the article is, but unless you’re aiming for a formal paper or something, try to keep the tone of it casual. I don’t mean don’t use technical terms, by all means, do, just don’t overuse them. Remember: just because you managed to understand the subject you’re explaining, it doesn’t mean your reader is at the same level as you! In fact, they probably aren’t!
Try to keep a light tone, present as many examples as possible, a lot of people learn better when they are shown a practical application of the theory. But end this section strong by putting all the practical examples you’ve shown into the context of the “theory” you’re trying to explain.
But before we continue, let me give you a few quick protips when it comes to writing the content for this section:
- Don’t underestimate the topic you’re writing about. Do your research, even when you think you understand what you’re talking about, it never hurts to know what others are saying about the topic. You can still decide to ignore the result of that research and go with your initial idea. But trust me, unless you’re covering a very obscure and unique subject, I’m sure someone else has shared their take on it, and that can help you as inspiration (do not confuse this word with plagiarism, get inspired that’s all).
- Be consistent with your speech and tone. If you’re directly talking to your reader, do so during the entire article. If on the other hand, you’re just presenting information and facts, stay like that and avoid having a dialog with your reader. However, if you do decide to mix things up, make sure the change is evident, and address it. This obvious change in pace will jump at the face of your reader like a scary facehugger from Alien. This can be a great resource to use when you want a particular section or topic to stand out (i.e notice how I specifically said I would list some protips instead of just listing them like they were part of this section).
- Avoid walls of text. Make sure your examples are simple and visual. I don’t necessarily mean to start using images, sometimes text examples are great (I use them all the time for the software development articles), just as long as the visual presentation changes. This can be a great tool to highlight your ideas and different sections of your body. In fact, some readers might even use them to skim through your article and see if this is indeed, what they’re looking for before actually sitting down and reading your content.
And now that you know what to write here and how to do it, the only thing you’re missing is a great closing section.
Closing Your Article
In this section you’re meant to write your closing statement. What is that you ask? Well, depending on the tone and content of your article, it could be one (or several) of the following items:
- A summary of your content. Meant to help your reader remember everything you said. This doesn’t have to be more than a list of bullet points, but it will help, especially if your article is long and covers multiple topics.
- Asking a question. This is a great way to involve your reader and get them to connect with you and other readers. Ask them a question about their own experience with the topic and they will engage with you and feel a part of the article.
- Thank your reader. A very common closing section as well is a paragraph thanking your reader for reaching this final section. If done correctly, it’s very effective, just don’t overdo it.
- Ask for a social share. A quick request from you to your reader. If they liked the content, it never hurts to remind them that they can share it with others. But like before, don’t overdo it, ask for a small favor, don’t share your life story as a motivation for them to share your work.
- Ask for a sub. Growing your mailing list is just as important (if not more) as growing your own following on any social platform. So asking for a subscription to anyone who managed to get to the bottom of your article is not a bad idea. Just make sure the ask is minimal and that you’ll keep the SPAM to a minimum.
- Link to other related articles. Platforms such as Medium already do this for you, but it never hurts to specifically link to other articles you’ve written, especially if they’re relevant to your content. This helps the reader in that they keep reading related articles and you to get further exposure.
- Link to external references used. This is particular useful for technical pieces. If you’re making an assertion about a fact, it’s always useful to list where that information came from (i.e your source), otherwise it’s your word the reader needs to trust. This also helps legitimize your article by providing other links where the information you’re providing can be found.
There are probably other, less common items to add to your closing section, just remember: it needs to be short and concise. By now the article is over and your reader should’ve gotten all the information they were looking for. Just try to mix some of the points from the list above that will help your reader and at the end, probably one or two call to actions (i.e the ones that require interaction from your reader and that will get a result you’d want, such as a subscription or a comment)
Some Final Words
That’s it, you’ve made it to the end and my hope is that by now you’ve learned one thing or two. Heck, maybe you have your own way of writing your blog posts, I’m just sharing my experience and the structure I usually use for my own technical articles. Other than this very one, you can also see other examples of my work that have been very popular. Review them, check their structure, you should be able to notice the similarities now:
Threads in Node 10.5.0: a practical intro. A few days ago, version 10.5.0 of Node.js was released and one of the main features it contained was the addition of…
What is Deno and will it Replace NodeJS. Deno v1.0.0 is scheduled for release on May 13. Here are a few interesting facts that may play a role in determining…
And to end things, let me ask you, what tips would you give to someone looking for the best way to write a technical article? Leave a comment down below and share your experience with everyone else!
Thanks for reading and see you on the next one!
If you liked what you’ve read, consider subscribing to my mailing list and I’ll keep you posted when new articles are ready!
Pin it for later!