Advent of Technical Writing: How-To Outline

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

A "how-to" is an article that explains how to accomplish a task or solve a problem. Online, many article titles start with "How to", which provide a clear indicator that the article will show how to do something. But, not all articles follow that title pattern. Any article that shows you how to do something is a "how to".

I often start my tutorials with a few bullet points of what I want to cover, or a few headings. These notes help me evaluate what I want to say in a piece of writing. By having a few notes, I am not starting with a blank page. The notes are the beginning!

With that said, you may be wondering: how do I know how to structure my article? How do I turn my notes into an article? For this post, I am going to focus on the "how-to". I have prepared a few bullet points which outline a structure. You can copy-paste these bullet points into a document to get started, read them now, or save them for later as a reference.

The how-to outline

Here is the structure I would use for a how-to guide:

• How to do {x}
• Introduction
  • A few sentences of background.
  • Introduce what you are going to do.
  • Say what someone will be able to do by the end of the article.
  • Link to related learning resources (a video, an interactive notebook (for data science, machine learning), full code documentation, etc.).
• What is X?
  • Introduce what X is.
  • Provide context on X (history, when it was released, notable features).
• Step #1:
  • First, we need to…
  • Include best practices.
  • Here is the result:
  • [result]
• Step #2:
  • ...
• Step #3:
  • ...
• …
• Conclusion
  • For product documentation, a conclusion should be short. Perhaps a single sentence.
  • For blog posts and technical tutorials, a conclusion should be longer (1-2 paragraphs), summarising the content.

Walking through the outline

Let me talk through these bullet points with reference to an example.

Suppose I have been asked to write an article about how to deploy a computer vision model offline. I might start the guide with the problem statement: deploying a computer vision model is difficult and time consuming. Then I would introduce the solution, which would be our company's product. I would then state exactly what we are going to do "By the end of this guide, we will have done X, Y, and Z." If the guide has a visual end state (i.e. a completed action in the product or code), I may include a screenshot to show the reader early on what the guide will enable them to do.

The introduction should provide all the information a reader needs to evaluate if an article is likely to be relevant to what they want to learn or the problem they want to solve.

After the introduction, I would define the task we are trying to solve, with reference to the solution, in more depth. I might start a section that says "What is Roboflow Inference?", where I introduce our solution to the problem of deploying computer vision models and state the advantages of the solution. I could include multiple sections that talk about the task, depending on what information you think is relevant.

From there, we get into the "how-to" section. Create new sections for each step. I would start each step by saying what the reader will do, then show how to do it. Reference code where appropriate. Add images when you need them. Any images you add at this stage should be directly related to the "how-to" (i.e. product screenshots, code results [^1]). Create as many sections as you need.

Then, we can conclude. In a conclusion, you should summarize what you said earlier. Do not introduce new information in a conclusion. If you feel like you are repeating yourself, that is okay. A conclusion is an opportunity for you to help the reader reinforce their learning. Include key facts about the product / API you are documenting. Summarise the steps the reader followed to achieve the desired outcome.

If you are writing product documentation, I recommend keeping each section short and to the point. A few sentences -- or even one sentence in some cases -- may suffice for everything from the introduction to each step to the conclusion. Product documentation should strive to be as short as possible. Blog posts and technical tutorials benefit from a more detailed introduction.

There is an expectation that a technical tutorial (i.e. how to use an API) contains learned insight beyond the exact steps someone needs to follow to solve a problem. For example, a blog post on "how to deploy a computer vision model offline" could explain the drawbacks of the current situation, with reference to experience. When you get a model working, you could show how to see the results (which involves more code.).

[^1]: If code results are in text, put the results in the article if they aren't too long. Screenshots of code results are not ideal; images take a while to load.