diff --git a/docs/contributors/documentation/README.md b/docs/contributors/documentation/README.md index 77c6f38ef5fc0..45e80bc9a0954 100644 --- a/docs/contributors/documentation/README.md +++ b/docs/contributors/documentation/README.md @@ -36,6 +36,12 @@ The handbook is organized into four sections based on the functional types of do - **Reference guides** - API documentation, purely functional descriptions, - **Explanations** - longer documentation focused on learning, not a specific task. +### Templates + +A [how to guide template](/docs/contributors/documentation/how-to-guide-template.md) is available to provide a common structure to guides. If starting a new how to guide, copy the markdown from the template to get started. + +The template is based on examples from The Good Docs Project, see their [template repository for additional examples](https://github.com/thegooddocsproject/templates) to help you create quality documentation. + ### Update a document To update an existing page: diff --git a/docs/contributors/documentation/how-to-guide-template.md b/docs/contributors/documentation/how-to-guide-template.md new file mode 100644 index 0000000000000..479219e5a95f1 --- /dev/null +++ b/docs/contributors/documentation/how-to-guide-template.md @@ -0,0 +1,56 @@ +# How to guide template + +## Overview + +A how to guide walks through a series of steps focused on completing a single task. The guide's goal is not on teaching concepts, but to answer the question "how do I ... ". + +The overview section summarizes the problem and can include context on how and where you might use the solution properly. + +## Before you start + +Include a section on assumptions and prerequisites: + +- Pre-requisite one: WordPress development environment +- Pre-requisite two: familiarity with JavaScript and Gutenberg +- Pre-requisite three: custom block or theme + +Include other important information here, such as known issues or bugs. + +## Step-by-step guide + +The guide should include step-by-step directions. Use code snippets, images, or screenshots to help illustrate each step. Include as many (or as few) steps as needed, try to keep each step short and easy to follow. + +### Step 1: Optional: title + +Brief instructions explaining the first step. + +### Step 2: Optional: title + +Lead-in sentence for an ordered list: + +1. Sub-step A +1. Sub-step B +1. Sub-step C + +### Step 3: Optional: title + +Lead-in sentence explaining the code snippet. For example: + +```shell +npm install +npm run build +``` + +## Troubleshooting + +- What can go wrong? +- What are potential error messages and what to do? + +## Conclusion + +Provide a summary of the steps completed and explain what the user has achieved. You can include links to related articles, more complex examples, or how to learn more on the topic. + +