Advent of Technical Writing: Consistent Examples

This is the twenty-first 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 you are writing a blog post that documents how to use a versatile piece of software, having an intuitive example that is relevant to your product is crucial. Clear examples aid understanding in what a piece of software does and how it solves a problem, in the case of both code products (libraries) and products with user interfaces.

It may be tempting to refer to many different usage examples for in a blog post. However, you should try to stick to one consistent example throughout a post and, optionally, have a separate section that lists additional use cases.

For example, consider a guide on how to search for frames in a video. This technology could be used on for media indexing, content understanding, and more. Throughout the post you should refer to one, consistent example.

I used to mention several uses in an introduction to a blog post, then potentially mention more in a section that defines required knowledge, before finally walking through one example in depth. It is easy to do this when a product is flexible, but many examples in different sections in an article -- even if they are only one sentence long each -- can be confusing.

Instead, I recommend:

1. Having a specific place where you mention examples. This could be your introduction or a dedicated "use cases" section.
2. Mentioning exactly what you are going to build in your introduction.
3. Following through with building that example application throughout the post.

In a guide I wrote on vsearching video frames, I showed how to search a movie trailer. Here was my introduction:

Imagine a search engine that lets you find frames in a video given a text prompt. For example, a search engine that helps you find all of the title credits in a trailer, all of the adverts in a broadcast, or all of the scenes that are in an office. With Roboflow’s video Inference API, it is possible to build such a search engine.

In this guide, you will learn how to use the Roboflow video Inference API to calculate CLIP vectors for frames in a video. We will then use these vectors to build a search engine that accepts text queries and returns timestamps for relevant frames.

I mention a few applications in the introductory paragraph. Then, I say that we are going to "build a search engine." I then refer only to this example throughout the main content of the post.

Above, I spoke about referencing many examples throughout a post. I also recommend using one well-researched, robust example, and keeping it consistent. If you need to show multiple product features, you should stick to the same example rather than introducing another example.

(Notice how in this guide I spoke only about the "build a search engine" guide, which I chose because I knew it would help me illustrate my point effectively.)

That's it for today's tip! Join me tomorrow for another technical writing tip.