Advent of Technical Writing: Clarity

Published on under the Technical Writing category.

This is the sixth 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.

Good technical writing is clear. I could make that statement and say “that’s all you need to know!” But that wouldn’t be clear! Herein lies a question: what does it mean to communicate technical concepts with clarity? Let’s talk through a few tips that will help make your writing more comprehensible and intuitive to your audience.

Challenging assumptions

Technical writers need to make assumptions. You need to assume some level of familiarity with a concept for each piece of content you write and use that assumption to inform what you say and how you say it. With that said, you should actively ask the question “is this assumption correct?”

Here is part of an introduction from a guide I wrote on how to analyze the color of a product:

In this guide, we are going to discuss how to analyze product color using computer vision. We will walk through an example of taking an image of a t-shirt and identifying the color of the shirt.

To analyze the product color in an image, we will:

  1. Use a segmentation model to identify the precise location of the object whose color we want to check, and;
  2. Use clustering to identify the most common color(s) in the image.

The title of the guide is “How to Analyze Product Color in Quality Assurance Processes”. This guide was written for anyone who wants to analyze product colors. I cannot assume that someone knows that computer vision is the solution.

I explicitly say that we are going to “analyze product color using computer vision.” I walk through the exact steps. When I say “use a segmentation model,” I imply what that means (“identify the precise location of the object whose color we want to check”). In hindsight, I could make this even clearer by saying “computer vision system,” then introducing the concept of “segmentation model” later. I say that we are going to use clustering to identify colors in an image. I say the how and the what.

The two bullet points above could be expressed as:

To analyze the product color in an image, we will:

  1. Use a segmentation model to find objects of interest;
  2. Use k-means clustering to identify common colours, then select the top color.

Compare the text above to the previous text. I say “segmentation model” without saying exactly what that entails. If a reader knows a bit about computer vision, they may wonder “why segmentation?” Therein lies a question I have sparked. A reader might not know what k-means is, even though that is the solution.

When you use jargon, make sure it is well explained for your audience. Don’t assume that someone knows something even if you do.

This, like so many aspects of writing, is a muscle. Something can feel so obvious to you that it doesn’t need to be said. A way to get better at this is to always work with an editor. An editor will point things out in your writing that you never notice.

One pattern I like to use is:

  1. Define
  2. Explain

Another way to think about this is with the following format:

X is Y. This means…

This pattern has helped me get used to stating a concept then explaining it immediately after. Using a new sentence to explain a concept in more depth is helpful. Long sentences can make writing hard to read.

How many words you use to explain a concept

When you are writing, say what you want to say in as few words as you can. Consider this text, which describes how to automatically label images for use in training a vinyl record detection model. This text is technical, so you may want to read the introduction of the quoted post to learn more context.

First, our code will use Grounding DINO and cut out all vinyl record covers. Then, CLIP will classify each cover and assign a label.

We need to calculate CLIP embeddings for one image that contains each class (SKU) we want to use in classification. Embeddings are numeric representations of an image that encode semantic information about the image. This information can be used to classify objects into categories.

The reference images we use should primarily feature the SKU you want to detect. Featuring multiple products will confuse the model and result in sub-par results.

The text above communicates a significant amount of information, including:

  1. The role “Grounding DINO” plays in a task (cut out vinyl record covers).
  2. How we cut out vinyl record covers (using “Grounding DINO”).
  3. The role “CLIP” plays in the task.
  4. CLIP embeddings are necessary to use cLIP.
  5. What embeddings are.
  6. What role embeddings play.
  7. Among other pieces of information.

With that said, we only used a few words. We say what things are and explain how they connect. It takes surprisingly few words to do this well. Verbosity is not rewarded in technical writing.

The UK government does a great job at communicating with few words. There is a clear impetus to invest heavily in this: their words need to be understood by all citizens. Every page uses short sentences that are clearly linked.

Here are a few examples:

I recommend reading over others’ writing and asking yourself the question “could this be expressed in fewer words?” This will help you build an editorial eye. Over time, you will start thinking to yourself “oh, this could be simpler.” Or “I can use fewer words to say this.” It is often easier to analyze others’ writing, especially as you begin, to look for patterns. You will learn what you like and don’t like.

Avoid superfluous language

One habit I actively fight against, and have noticed in other people who communicate technical concepts in written language, is the tendency to include superfluous words. These are words and phrases that don’t add much value to a sentence.

Consider these two statements:

The Roboflow Video Inference API is a hosted solution that enables you to run any Roboflow Inference model for video processing. You can run custom object detection, segmentation, and classification models for identifying visual data specific to your domain.

Versus:

The Roboflow Video Inference API is a hosted solution that enables you to run any Roboflow Inference model for video processing. This API is designed to let you run custom object detection, segmentation, and classification models for identifying visual data specific to your domain.

The first sentences are taken from a guide I wrote that introduces a video inference API. I have adjusted the second sentence in the revised version above.

Notice that the second text says “is designed to let you run”. These words don’t add much value to the sentence. We don’t need to say “designed” because the existence of a dedicated API suggests it was designed for a purpose. “to let you run” doesn’t communicate information. An API should enable someone to do something.

Let’s break out these sentences:

You can run custom object detection, segmentation, and classification models for identifying visual data specific to your domain.

Versus:

This API is designed to let you run custom object detection, segmentation, and classification models for identifying visual data specific to your domain.

Both communicate roughly the same information, but the first is more concise. It relies more on what was said in the last sentence and uses fewer words to explain the same concept. The value proposition is clearer in the first sentence. “You can run” is a call to action. More broadly, “you can” is a powerful set of words. Those words can empower the reader and help them feel like a task is achievable. “This API is designed to let you run”, on the other hand, is less interesting and less engaging.

Another category of superfluous language is words that aren’t jargon that could be simpler. Technical writing involves effort for a reader to comprehend. The more complex words you use, the more effort required to understand a concept. For example, use “use” instead of “utilize.” “Process” instead of “pipeline.”

Being more direct, removing superfluous language, and using simpler words where ones are available are details that make a notable difference in a reader’s ability to understand what you are communicating.

Join me tomorrow for another technical writing tip!

Go Back to the Top