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
- Save reader's time in doing something
- 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,
- How much time it takes to complete?
- What you need beforehand? e.g. software, hardware, licenses etc.
- What they must know? e.g. cost, high level concepts, legal disclaimers etc.
- What they will achieve at the end of this? e.g. example output
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.
