The what, why, how formula of technical writing

When I am writing technical content, or editing others' work, I ask myself three questions:

• Does this content describe what it should describe?
• Does this content explain why the reader should be interested?
• Does this content state how the reader can accomplish a stated task?

These three questions allow me to evaluate the extent to which my writing and the writing of others follows through on its stated goals. If a guide answers all three questions above -- whether the guide is product instructions, a coding tutorial, educational material, or reference material -- I feel confident that the content is going to guide a reader in the way I or the author intended.

Let's explore each of these questions one by one. To walk through these questions, I will reference an example of a tutorial I wrote that explains how to train a keypoint detection model. Keypoint detection is a computer vision task that aims to identify points in an image (i.e. points on a human arm). You don't need to know anything about computer vision to read on.

Let's get started!

The what

Does this content describe what it should describe?

When you are writing technical content, you should always ask whether your words accomplish the stated goal of your article. Your goal might be to teach someone a skill or walk someone through a series of steps in a product. Whatever the goal, you should:

1. Clearly state what the reader can expect from the guide, and;
2. Provide all the information the reader needs.

Consider my guide on how to train a keypoint detection. In the opening paragraph, I say:

Keypoint detection enables you to identify specific points on an image.

This educates the reader on what keypoint detection is. By including this, I can ensure the reader has the relevant context to get the most out of the article.

Then, I say:

In this guide, we are going to show you how to label data for, train, and test a keypoint detection model in the cloud using the Roboflow platform.

In this one sentence, I state exactly what the guide does. This helps a reader evaluate what is in a post and also gives me clarity on what I should write about. If you are struggling to figure out what is relevant in an article, list three things you think are important and try to fit them in a sentence starting with "In this guide, we are going to..."

This wording will help you solidify what you want to talk about. Then, as you write, you can come back and ask yourself "have I explained what I promised?" If you feel information is lacking on one of the "what's" of your article, you know to go back and revise your work to add information you think is relevant.

After this commitment where I say "we are going to show you...", the keypoint guide follows through. All the information a reader needs to label data for, train, and test a keypoint model in the cloud is in the guide.

Another trick to see if you have followed through on the what is to look at your table of contents. Are any sections missing you think are relevant? For example, if the keypoint guide was an introductory piece intended for students I might add a more detailed "What is keypoint detection?"

The why

Does this content explain why the reader should be interested?

Technical content is by its definition technical. You will use jargon to explain concepts (although please do so mindfully and explain all jargon as you go!). When you introduce a concept, you should aim to answer a question that will be in the reader's mind: is this material relevant for me?

In many cases, a title may grab a reader's attention. But, this may not be enough. If a reader is unfamiliar with the topic at hand, you need to convince them why your guide might be relevant. It is okay if your writing isn't relevant. Indeed, your job as a technical writer is not to convince people to read a specific piece of content. It is your job to guide the reader to solve problems, even if that means pointing them elsewhere.

Explicitly stating what you are going to discuss in part answers the question "why should the reader be interested?" For example, if I wrote a guide that aims to answer the question "What is keypoint detection?" and I don't say that I am going to show how to train a keypoint detection model, a reader who wants to train a keypoint model will know the guide is not for them. This is okay: technical content should be focused. It is best to stick to one topic than try to address every possible topic.

Another effective way to explain why a reader should be interested in a piece of content is through use of examples.

Consider the keypoint detection guide. In the introduction, I note three examples of when keypoint detection is useful:

For example, you can use keypoint predictions for pose estimation of a person during a tennis game or you can use keypoint detections to measure the envelope of a robotic arm.

...

We will train a keypoint detection model to identify key points on glue sticks. The points we will identify are the top and bottom of the glue stick. This model could be used on a manufacturing line to ensure glue sticks are oriented properly before reaching the packaging stage of the production line.

Here, I mentioned that keypoint detection can be used for:

• Estimating the pose of a person, with reference to a sports example.
• Measuring the "envelope" of a robotic arm, a promising application of keypoint detection. We referenced this example since it might light a spark in someone's mind about what is possible; keypoint is applicable to a range of robotics use cases.
• Identifying points on glue sticks, which could be used in a quality assurance process.

With these three examples, a reader can get a taste for what keypoint detection will allow them to do.

Notably, keypoint detection is commonly used to refer to pose estimation, a task where you estimate the pose of a person. This application is commonly used in safety tools and exercise applications. But, the possibilities are much greater! Through the non-pose examples, I am able to show a reader that keypoint detection -- the topic of the guide -- is more than what you may think. For a reader with manufacturing experience -- a common reader of our content -- the glue stick example may encourage them to think oh, keypoint is more than I thought!.

The how

Does this content state how the reader can accomplish a stated task?

You should have a clear goal in mind when you are writing content. You should refer to that goal to make sure you say everything you need for a reader to understand a concept or accomplish a task. If your content is a tutorial or reference guide, your content should clearly state how the reader can accomplish the stated task.

In the keypoint guide, there are seven sections that talk through how to label data for, train, and test a vision model:

Step #1: Create a Keypoint Project Step #2: Define a Skeleton Step #3: Upload Data Step #4: Annotate Key Points on Images Step #5: Generate a Dataset Step #6: Train a Model Step #7: Test the Model

In each step, I explain what a reader needs to know to proceed through the guide. By the end of the guide, the reader will have a trained computer vision model, as promised in the introduction. Be comprehensive in your explanation. A guide should explain how to solve a problem without requiring any knowledge that is unreasonable to expect of the reader (read: a beginner's guide should not require intermediate or advanced knowledge to understand).

To make sure you explain the how of your content, consider sharing your content with a colleague who is unfamiliar with the topic in your guide. Ask them to follow your instructions. If they get confused at any stage, you have found an opportunity for improvement. If the reader cannot achieve the end goal, you can work with them to identify the step(s) missing in your content.

Conclusion

During revision time in school, I would write down all of the essential points of an essay and memorize them. I used those points as anchors. If I remembered those essential points, my mind would remember other related facts. I started the essay with the essential points. I will share them again as your anchor.

When you are writing content, ask yourself if you are:

1. Does this content describe what it should describe?
2. Does this content explain why the reader should be interested?
3. Does this content state how the reader can accomplish a stated task?

Or, more concisely, make sure you explain the what, why, and how in your content.