How to Write a How-To Guide
What is a How-To Guide?
A How-To Guide is a practical step-by-step guide that helps readers achieve a specific goal. How-To Guides are most useful when readers want to get something done.
How-To Guides work well for outlining procedures that readers need to follow. You can think of a How-To Guide as a recipe used in cooking. It walks you through the steps to complete a task, from start to finish. It should only include as much context as is needed to help users achieve their goal.
A How-To Guide can include some details to help users understand the steps they’re following. For example, you should add a quick sentence before showing a code snippet, to explain what the code does (at a high level) and which pieces to pay special attention to. If you find yourself wanting to provide deeper explanations of how something works, consider creating a separate Reference Guide or Conceptual Guide and then linking to it in the How-To Guide.
For more information on How-To Guides, check out the Diátaxis documentation system, which the Gatsby docs are based on.
How-To Guides audience
How-To Guides are for anyone looking to complete a common Gatsby task, however they may appeal to intermediate to advanced learners due to their brevity and focus on Gatsby-specific details without going through every setup step.
How-To Guides tone and style
How-To Guides are shorter and more concise than the Tutorial but more hands-on than Reference Guides. They should be friendly but information-dense. This is accomplished by focusing on only what is relevant and actionable to the given task, anticipating any new or difficult concepts with links to additional materials to continue learning.
A near-perfect example of a How-To Guide
Want to see what a good How-To Guide looks like? Check out the How-To Guide: Add a Plugin to Your Site.
How-To Guide template
The title of your How-To Guide should specify what it helps readers do. You should be able to add the words “how to” to the beginning and have it make sense. For example, if your guide is about “how to create a new layout component”, the title would be “Create a New Layout Component.”
A How-To Guide should include the following sections:
- Introduction: Provide some quick background information to help readers understand 1) what this How-To Guide will help them achieve and 2) why that’s useful.
- Prerequisites: Any additional information or setup readers will have to do before they can make use of this How-To Guide.
- Directions: List out the steps that readers to follow to complete the task. Use code blocks to show exactly what readers should type in their own projects.
- Additional Resources: Links to other docs or content that might be useful next steps for readers. Also, any resources that helped you write the How-To Guide.