Docs: Add how to guide documentation template (#36694)

* Update documentation contributors guide with types - Adds new section that explains how the documentation is organized around types - Updates headings to match sentence case as recommended - Minor text tweaks and updates * Markdown linting * Add how to guide template * Update docs/contributors/documentation/how-to-guide-template.md Co-authored-by: Alex Lende <[email protected]> Co-authored-by: Alex Lende <[email protected]>
WordPress · Dec 7, 2021 · 2f7f045 · 2f7f045
1 parent 63deb10
commit 2f7f045
Show file tree

Hide file tree

Showing 2 changed files with 62 additions and 0 deletions.
diff --git 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
@@ -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.
+
+<!--
+This documentation is based on templates from The Good Docs Project.
+This comment can be removed in your guide.
+-->