Writing introductions in technical tutorials

When I am writing an introduction to a technical guide, I usually follow a format like this:

1. Introduce the main concept being discussed in an article, with relevant background.
2. Reference an example to which I will refer later in the post (optional, depending on the length of the background in the opening paragraph(s)).
3. Summarise, in a few points, what will be discussed in the article.
4. Show an example of what someone will accomplish by the end of the article, if possible (most relevant for visual guides such as those that pertain to web design, image editing, computer vision, etc.).
5. Conclude with a welcoming sentence that eases the reader into the main content.

Here is an example from a recent tutorial I wrote for work on SAHI, a technique that enables you to detect smaller objects with a greater degree of accuracy using computer vision models:

Detecting small objects is a challenging task in computer vision, yet significant for many use cases. Slicing Aided Hyper Inference (SAHI) is a common method of improving the detection accuracy of small objects, which involves running inference over portions of an image then accumulating the results.

In this guide, we are going to show how to detect small objects with SAHI and supervision. supervision is a Python package with general utilities for use in computer vision projects. The supervision SAHI implementation is model-agnostic, so you can use it across a range of models. We’ll walk through an example of detecting objects of interest in a beach image with SAHI.

Here is an example of an image on which inference was run with and without SAHI:

[image]

Without further ado, let’s get started!

This example follows the structure I outlined at the beginning of this post. I introduce the technique (SAHI), what we are going to do in the article (detect small objects with SAHI), how we are going to do it (use the supervision Python package), some important information about SAHI (it is model-agnostic), an example we are going to talk through (a beach image), and include a photo showing the results of the guide. You can see the photo yourself in the SAHI blog post.

I want my introductions to set expectations, ease a reader into a topic, show what we are going to do, and explain how we'll do it.

I like to end posts with a variant of "Without further ado, let's get started!" or "Let's begin!" because I think it sets a nice tone for a post. I want readers to feel like they are following a guide with me, rather than being told how something is. This is important to me. The key to good technical writing is that it is tailored to an audience and approachable for that audience.

This is my take on an introduction. Everyone has their own style, informed by their experience and the types of content they write; there are few hard rules about introductions. Ultimately, it is up to you, the writer, to figure out what you want to say and how you want to say it!