All articles require a great intro, after all that’s the second thing our readers get to experience after reading the title of the article. And many writers do spend quite a lot of time honing their introductory paragraphs to capture the reader with a metaphorical ball and chain. They glue them to the chair with their words, and they’re not able to leave until they’ve finished reading the whole piece.

However, there is one particular type of article that many believe to not require an intro at all: technical articles.

Technical articles are often written to teach someone about something, whether it’s about new technology, or how to perform a certain task step-by-step. The point is that some authors assume the reader will skip the intro, or skim quickly across it to get to the “good part” and follow the instructions.

This is not true.

A technical reader also needs a good introduction, they also need to feel the need to keep on reading. Technical articles can be very long and boring otherwise.

So let’s take a look at some do’s and don’ts when it comes to writing the introduction to your next technical article.

Don’t: Focusing on the output

Many authors simply state the things the reader will know after reading the article:

“After reading this article, the reader will know how to conditionally hide a React component using one of the 7 techniques presented here.”

That’s it? That sounds more like a pitch for an editor than what the reader wants to know. Granted, at least it’s informational, but they probably knew that much already given they decided to read the article to begin with.

What are you telling them that they don’t already know here? Nothing. In fact, if I was editing that piece, I would simply remove the whole introduction, those words don’t add any value. And writing in general, but specifically technical writing, should be about giving some kind of value to the reader.

Don’t: Skip the intro and jump straight to the topic at hand

You might be tempted to simply skip any type of introduction, after all if the reader already knows why they’re there, what’s the point, right?

Wrong.

The reader doesn’t always know why they’re there, they know what topic you’re going to cover. Those are two very different things.

Telling them “We’re going to be covering how to connect to a remote MySQL database from PHP” as an introduction to an article titled “Connecting to a remote MySQL DB from PHP” is completely redundant, yes.

However, why did they click on that topic? No matter how basic or trivial you think the topic is, someone’s probably having problems around it, which is why they clicked on it. So find a way to show them that you understand those problems. If you get that right, the reader will relate to your writing. It’s not going to be a simple case of copy&pasting, they’ll love your piece and they’ll want to share it with others having the same problem.

Never skip the intro.

Don’t: Focusing on requirements

“To follow along, you’ll need to have installed Node.js (version 14+), MySQL and any Linux distribution will do.”

That’s not an introduction.

Why is the reader here? Why did they click on the title to begin with? To understand requirements? Nope, that’s not it.

I don’t like listing requirements on my technical articles and I don’t think they really add any value to the piece. The requirements will be implied by the topic at hand (for example, any web developer knows that they’ll need Node.js if they’re using Webpack, or any JAVA developer knows they need to have the JDK installed if they’re trying to do anything). The only moment where you should mention a specific requirement is if you need a very specific version of a library or module.

“Note: this will only work with Node.js version 15 or higher”

That’s completely valid, however, that’s not part of the introduction, that information is only shown precisely where it’s needed.

Do not focus on requirements, especially not during the introduction to your article.

Do: Start with a joke

Why not? The reader is not going to expect it, and if it’s a good joke then they’ll keep on reading with a smile on their face.

That’s going to set the tone for how they take the rest of what you have to say. Just make sure that the joke is relevant to the topic at hand.

An unexpected joke, probably made up by you on the spot, is going to break any mental model the reader might’ve had about the topic you’re discussing in that article.

Consider that for a moment.

If you’re writing about your take on a piece of technology for example. Whoever comes to read your thoughts on it will have a pre-conceived idea of what it is and thus, they’ll have their own opinion about it. In other words: a mental model.

In their head they’re probably expecting you to say what they already think about it. If they like it, they’ll expect you to praise it, if they hate it, they’ll be expecting you to hate it as well. It’s hard to get through to everyone this way.

However, by giving them something completely unexpected you’ll shatter that mindset. And then you’ll have a few seconds to rebuild it however you like it, so take that time to write a proper introduction that sets the right tone, they’ll be more open to it now.

Just make sure that:

The joke is short. The actual introduction should come after the joke, so don’t make it 10 lines long. Try to go for a one-liner if you can, get to the fun part sooner rather than later, otherwise you’ll lose the reader’s attention and they’ll leave. After all, they did not get there to read jokes, they were looking for something else. This should be a quick surprise, like sucker-punching them in the face when they least expect it.

Do not be offensive. If you are, you’ll lose people, so why bother?

Don’t try to be smart about it. If the joke is not remotely funny, they won’t get it. They were not expecting a joke there, so if it’s not funny or at least, clearly a joke, they’ll be confused and they’ll think that’s your introduction. They won’t understand what they’re looking at and they’ll probably hit the back button on their browser.

Do: Show them you understand what they’re going through

They probably clicked on your article because they have a problem they want to solve. Then start your intro by covering a similar problem. That way they’ll relate to the piece and they’ll reader carefully word by word of what you have to teach them, hoping it will be the solution to their problem.

Don’t get overwhelmed by this technique, sometimes a piece of tech or even a generic concept such as “The observer pattern” can be used to solve many problems.

In those cases, don’t be super specific, instead try to be generic as well. Come up with a type of problem that can be solved by this topic and quickly explain it as part of your introduction. Then finish it by stating that you’ll teach them how to solve that problem.

Notice I didn’t say “tell them what you’re going to teach them”. That’s already part of the title, instead, you’re giving them the promise of “salvation”. They now believe your article is the solution to their problem (whatever that might be).

Do: Tell them how relevant the topic is

Sometimes we might not be writing about a solution to a problem, instead, we might just be covering a specific technical topic because others must know about it.

In these scenarios, if we set up the reader with a problem, we’ll narrow the reach of the topic around solving that problem. So instead, focus on how relevant that topic might be for the reader.

After all, we’re only trying to get the reader to understand that they need to continue reading because our article will add value. Whether that is through teaching them how to solve a type of problem, or by giving them information that is relevant to their career, that’s not important.

So if you can’t come up with a good classic problem, or if you will not be solving anything, then start by explaining why this topic is a “must-know” for the reader.

Is it a concept that gets used across many industries? Is it going to become relevant when they start doing code reviews? Are they probably incurring a code smell because they don’t know about it?

See what I did there? Who wouldn’t want to keep on reading if you start by telling them how important that topic is? Just make sure that you phrase it in a way that helps them relate to it.

Saying:

“Dependency injection is important because it prevents programmers from using global variables”

Is not the same as saying

“By understanding what dependency injection is, you’ll realize you’ve been using global variables (which is a big no-no when it comes to coding) when you could’ve been doing something else.”

Both intros state the same and focus on the same thing: the importance of understanding dependency injection.

The first example is generic, it leaves it to the reader to figure out if using global variables is a problem or not (and they might now know the answer to that question).

However, the second one speaks to the reader, it connects to them and shows them you know they’re using global variables, and that it is a mistake. They feel seen and, in this case, probably a bit ashamed because they’ve been caught doing something wrong, something they’ll want to learn how to solve quickly.

So to sum it up, because it’s getting long enough, the main points you have to remember:

Do not consider your technical article like something a machine will consume. It needs to be entertaining and carefully crafted to keep the reader’s attention.

It’s not enough to show them how to do something, or to tell them about something. They need to understand the value they’re getting.

Consider capturing their attention fast during the introduction by shattering their preconceived mental model. By showing them you know the problem they’re having and telling them you know how to solve it. Or even by connecting with them and showing them that you’re giving them relevant information they need to know.

Did I miss anything? How do you start your own technical articles? Do you have another technique you use? Share it in the comments!