✍ How do you write good how-to guides?

By Nilesh Mahajan

📅 Feb 22, 2021

4 min read

With companies going remote and distributed, writing good "how-to" are essential for quick onboarding of customers and employees. So share some tips on how to write them well.

How-tos are immensely popular types of content that are frequently clicked upon by readers looking for solutions to their problems. I approach it from the angle of someone who is writing software how-to documentation like a developer - sharing showing off how to build something, or a developer advocate - walking developers through their API/platform capabilities or a solution architect - giving clear instructions to customers about building a solution.

The amount of effort for writing a clear and concise how-to guide is often underestimated. Most how-tos on the internet look like a dump of someone's personal notes with code snippets and screenshots. So before we jump to some tips to write good how-tos, let's first understand the motivation of writing how-tos.

Why do we write how-tos?

The core intentions behind writing how-tos are

  1. Save reader's time in doing something
  2. Save reader from making serious mistakes.

How-tos and tutorials are not the same thing.

Many writers often confuse how-tos with tutorials. Unlike tutorials, learning is not an objective from a how-to guide. Imagine getting an IKEA assembly instructions book with in-between notes teaching you - the history of nuts and bolts. Does the reader really care about that stuff while they are assembling a sofa?

How-tos are just about solving a problem with provided step-by-step directions.

So in a way, you should assume the reader's familiarity with underlying basic concepts about the technology they will be using.

Characteristics of Good How-tos

1. Singular objective

Each how-to guide should have one clearly defined objective. Having multiple objectives as part of the same how-to can be troublesome to readers and can lead to mistakes.

2. Upfront expectations

👉 Clear title

Writing a clear title will make sure the reader understands the objective well. In fact, it is advisable to always have a title like - "How to do X?" so that it forces your thought process to stay on course while writing the steps. It also helps in discoverability of the guide

👉 Clear pre-requisites

Before jumping into a how-to, explain the pre-requisites so that reader does not learn about those while in the middle of executing steps like,

3. Clear steps and instructions

👉 Break down into steps

Break down the content into smaller and logical steps. It helps readers build muscle memory.

👉 Add assertions

Each step should have some sort of assertions. It ensures that readers are on the right path and act as a positive encouragement to finish through.

👉 Use and annotate screenshots/images

Screenshots help generate confidence. Use good tools to annotate part of the screenshot you want the reader to pay attention to.

👉 Code snippets

Share code blocks entirely but explain only important snippets of code that the reader should pay attention to.

4. Conclusion and references

At the end of guide, point readers to next guides and references relevant to current topic.