Follow me on Twitter, happy to take your suggestions on topics or improvements /Chris

Writing, like most things in life, is an acquired skill that you can improve on by giving it time and deliberate practice. But what does it mean to improve your writing? You can definitely work on sanitary factors like spelling and grammar and there are great tools for that like Grammarly for example. However in my opinion, as the writer of several books, the biggest gain to your productivity, as well as readability for your readers, comes in understanding and mastering structure.

There are certain topics I will touch on, that in my opinion can greatly boost your writing ability:

• the title, this is how you get people to click your article in the first place. The title should capture what it is about but preferably also at what level it is being conveyed e.g beginner, advanced and so on among other things
• introduction, this should give the reader the necessary context to what something is and why it is important and also what skills are being taught
• middle, this should tell the story and the points you are trying to make in small incremental steps
• the end, this should summarize the learnings of this article and it should show how you made good on your promise and actually taught the readers what you promised them

Give it a great title, but stay honest

As mentioned initially giving your article a great title is imperative to have people click your article link in the first place or pick up your book in a book store, if we are being a bit analog ;)

Let’s try to define what a great title is by looking at different types of titles and what they mean:

• The informative title, this type of title is very clear and tells you exactly what you are getting, for example, “Learning to test with the library Jest in React.js”. This gives us the skill we are being taught e.g testing, using what library Jest and in what context React. Informative is good and clear, but not necessarily great. It will speak to an audience that knows exactly what they need but it won’t draw people in who weren’t actively looking.
• The clickbaity title, this type of title will try to use an expression and sound “cool” to get your attention and hopefully the rest of the title contains enough information for you to want to click it. Example of this kind of title is using expressions like “Learn to test Jest Like a boss”, “The 5 steps to a better-written test suite” or “10 easy ways to improve the quality of your tests”. The point with this kind of title is to make a promise. It promises that something is not as hard as it seems or it promises to make you really good at a certain skill with relatively little effort, for example by reading this blog post. This is a great way to get people to click your article, but remember, you need to make good on your promise. You need to show them how easy it is to use something or that your 5 steps are really well thought out. This is about trust, you will build a readership over time and if your articles are always of this sort and you don’t deliver people won’t read your things anymore.
• An experience-based title, in this type of title it is promising the content to be valuable based on someones collected wisdom from many projects or many years in the profession. Example of this kind of title is “Lessons learned on testing from building 10 React apps of varying size” or “The 10 most important dos and don’ts of Sofware engineering — acquired wisdom from 20 years in the profession”. This is really the best kind of title, in my opinion, but not everyone has been at it for 20 years, so there's that :). In case you are wondering, yes I opted for the most clickbaity of titles and it got you here and hopefully, you will stay for the remainder of the article :)

The Introduction, set the scene and tell them why

Call me Ishmael. Some years ago- never mind how long precisely- having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world.

This is about giving the reader enough context to be able to read your article without too much prior knowledge. You want to make it accessible, don’t you? Not every article is a beginner article so the amount of needed context can therefore vary. If it’s an advanced article then maybe a few paragraphs are needed and maybe a good link to further explanations. If it’s very technical, consider a list of acronyms that you explain initially so the reader knows what you are talking about.

Context is one thing but even more important is the why, why the reader should read your article. It should answer why this angle or topic is important and why the angle of your article is relevant.

Another thing that is important, is if your article aims to teach a set of skills (not all articles do), is to list the set of skills they are about to learn. Creating a good list here might be the deciding factor whether the reader decides on it is worth reading your article or not. A list should start with a verb and also explain the skill. Let’s look at some examples:

In this article we will:

• Learn the basic concepts of testing
• Uncover the different types of testing
• Understand how to manage your tests and test suite
• Master the most important commands in Jest to leverage the library to its fullest

Above we use different verbs such as Learn to say we are teaching you a skill. Uncover, this is like teaching you a skill but it conveys information and concepts you might not even know about beforehand. Understand, this is synonymous to learning but it implies that things might need to be understood from different angles or it has many moving parts and so on. Master, this is a big word that I try not to use too much. However, if this section will really upskill the reader in terms of being able to work faster, more efficient or anything in that line direction, it can be motivated to use.

Treat the middle like a souffle, light and fluffy

This part is the “meat” of your article and well this is where you are supposed to be the subject matter expert. What’s important here, in my opinion, is to not overwhelm the reader with too long or many paragraphs or sentences. Let your personality shine through. Don’t make the text too dry, the reader needs to see that a human wrote it so have fun, I am :).

Keep the sections small and to the point and create subsections if needed. Most definitely over explain concepts and opinions, what’s obvious to you might not be obvious to the reader. Good tools to use here is:

• bullet lists, you are looking at one :) This is a great way to tell the reader a certain skill or topic needs to be taught in steps and it also sets them up for what’s about to come.
• images, images can be great to explain a flow and/or convey an emotion or reinforce a point.
• quotations, a quotation correctly placed is a great thing in the text to get the gist out of many paragraphs or even many sections. This might actually be the one thing the reader remembers from your article 2 weeks later so spend some time on content, wording, and placement. Generally, in my opinion, the headlines of the middle part should have a strong connection to the skills or topics that you mention in the introduction so it’s easy to see for the reader that they get what they are being promised.

One final advice here is to work with header and sub-headers in an iterative way, you might need to restructure a few times before you get the right amount of text under each header and the hierarchy of the headers makes sense.

The end, making it stick

Now depending on how well you did the other parts the reader might get here or they might have bailed out already, cause there is only so much time in the day or they have a life to live ;)

Jokes aside, getting readers all the way to the bottom is an accomplishment. The reader should be rewarded at this point with a reinforcement of the knowledge the article was supposed to teach them and some praising words and possibly also a funny gif, if appropriate.

So in this article, we covered how important a title is. We also covered how to write a good introduction and snuck in a quote from Moby Dick, did you notice? :) Thereafter we discussed the middle part and how it can be compared to food but mostly how to not bore/overwhelm the reader. Finally, we reached the end of this article and before we part let’s say some final words.

It’s very important that the reader understands where to go from here, what other things is there to read in the topic and if this is a tutorial what’s tutorials are on the right level to take me to the next step. I did promise you a GIF, so here it is:

Further reading

A clickbaity but to the point article:
https://www.wikihow.com/Create-a-Good-Article

A similar article with a little more description
https://www.examenglish.com/FCE/writing_an_article.html

Grammarly, free to use grammar checker
https://www.grammarly.com/