Advent of Technical Writing: First Sentences

This is the third post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

When I am writing product and software documentation (i.e. open source documentation, product guides) that explains how to do something, I like to start the document in one of two ways. This post does not cover blog post introductions, which I write differently. Read about how I write blog post introductions.

In many cases, I start the main content in documentation with 1-2 sentences that introduce a feature and what we will accomplish. Here is an example:

With Supervision, you can easily annotate predictions obtained from a variety of object detection and segmentation models. This document outlines how to run inference using the Ultralytics YOLOv8 model, load these predictions into Supervision, and annotate the image.

This text appears at the start of a guide on how to detect and annotate objects with the supervision Python package. I start the article by introducing the topic: you can annotate predictions from different models. Then, I talk about what we are going to accomplish. After these sentences, the article begins.

Here is an example of the first sentences in a guide called "Run a Fine-Tuned Model":

With Inference, you can run any of the 50,000+ models available on Roboflow Universe. You can also run private, fine-tuned models that you have trained or uploaded to Roboflow.

This guide proceeds to document running models from Universe and fine-tuned models.

The language above was crafted to be clear and consise. With these two sentences, the reader learns:

1. Roboflow Universe has 50,000 models they can run.
2. You can deploy those models on Inference ("Inference" is the product name).
3. You can run fine-tuned models on Inference, too.

Then the guide explains how.

Alternatively, you may opt to go directly in to the post content, such as in the example below, taken from a documentation page shows how to add team members to an account:

To invite a team member to a Workspace, add their email address in the Workspace Members section of the workspaces settings.

[image showing how to do this]

Introducing that you can add team members is not relevant, since it can be assumed from the title of the documentation that you can add team members. Thus, the page delves immediately into the intent of the page, without preamble.

Join me tomorrow for another technical writing tip!