docs: update /contributing docs (#30607)

* chore: group docs contributions pages into a subfolder

* wip: update docs templates overview

* wip: outline How-To Guide template

* wip: remove reference to www directory

* chore: add image with doc type quadrants (from divio)

* wip: outline 'how to write a X' docs

* docs: first draft of 'how to write a how-to guide'

* docs: add context to intro of blog contributions page

* docs: add TODO reminder about updating the doc system image

* docs: add numbered list of steps to how-to guide

* docs: update how to use a plugin, to match How-To Guide template

* docs: add how-to guide exemplar to /contributing template

* docs: update how-to guide template

* docs: copy edits

* docs: (wip) update reference guide template

* docs: create conceptual guide contributing doc

* Also moves data fetching doc under correct docs subfolder (/docs/conceptual)

* docs: update heading capitalization to match style guide

* docs: create reference guide contributing doc

* docs: update docs template landing page (rename to docs structure)

* docs: update the point to Support page instead of Twitter

* docs: update docs contributions guidelines (local dev setup, links, etc)

* docs: apply suggestions from code review

Co-authored-by: Lennart <lekoarts@gmail.com>

* chore: delete stub pages

* remove stub issue

* docs: update style guide

* docs: apply suggestions from code review

* fix: lint

Co-authored-by: Lennart <lekoarts@gmail.com>

docs/contributing/blog-contributions.md

@@ -2,7 +2,9 @@
 title: Blog Contributions
 ---
 
-If you'd like to contribute a post to the Gatsby blog, please review the process and guidelines outlined below and submit your idea for the post to our [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF)
+Blog posts are a great way to share your own experiences working with Gatsby at work or on a personal project.
+
+If you'd like to contribute a post to the Gatsby blog, please review the process and guidelines outlined below and submit your post idea using the [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF).
 
 ## Blog proposal submission process
 

docs/contributing/docs-contributions/docs-structure.md

@@ -0,0 +1,43 @@
+---
+title: How the Docs are Structured
+---
+
+## Introduction
+
+If you're looking to contribute to the Gatsby documentation, it helps to first understand how the docs are organized. This page outlines the overall structure of the Gatsby documentation. It also provides guidance on when you might choose one type of documentation over another.
+
+## Documentation Types
+
+The [Gatsby documentation site](/docs) includes four different types of materials. Each one is tailored to meet a specific user need.
+
+- [**How-To Guides**](/docs/how-to/) are practical step-by-step guides to help readers achieve a specific goal. These are most useful when readers are trying to get something done.
+- [**Reference Guides**](/docs/reference/) are nitty-gritty technical descriptions of how Gatsby works. These are most useful when readers need detailed information about Gatsby's APIs.
+- [**Conceptual Guides**](/docs/conceptual/) are big-picture explanations of higher-level Gatsby concepts. These are most useful when readers want to deepen their understanding of a particular topic.
+- The [**Tutorial**](/docs/tutorial/) is a self-contained introduction that guides readers step-by-step through creating their first Gatsby site. This is most useful when readers are first getting started with Gatsby.
+
+![Each of the four types of docs has a different intended audience. The Tutorial is for learning-oriented readers, who want practical steps to help when they're studying. How-To Guides are for problem-oriented readers, who want practical steps to help when they're working. Reference Guides are for information-oriented readers, who want theoretical knowledge to help when they're working. Conceptual Guides are for understanding-oriented readers, who want theoretical knowledge to help when they're studying.](./doc-type-quadrants.svg)
+
+> This documentation structure is based on the [Divio documentation system](https://documentation.divio.com) created by Daniele Procida.
+
+### Choosing what type of doc to write
+
+Trying to decide which type of documentation is the best fit? Check out the following guides:
+
+- [How to Write a How-To Guide](/contributing/docs-contributions/how-to-write-a-how-to-guide/)
+- [How to Write a Reference Guide](/contributing/docs-contributions/how-to-write-a-reference-guide/)
+- [How to Write a Conceptual Guide](/contributing/docs-contributions/how-to-write-a-conceptual-guide/)
+- [How to Write a Tutorial](/contributing/docs-contributions/how-to-write-a-tutorial)
+
+The guides above provide more details about each type of documentation. They also include templates and tips for how to write them. Use these resources to make sure your docs contribution fits the overall documentation structure.
+
+Sometimes, a single concept will require some combination of these documentation types. For example, the `gatsby-plugin-image` documentation includes the following pieces:
+
+- [Gatsby Image plugin](/docs/reference/built-in-components/gatsby-plugin-image/): A Reference Guide to explain the plugin API and all its options.
+- [Using the Gatsby Image plugin](/docs/how-to/images-and-media/using-gatsby-plugin-image/): A How-To Guide to show practical examples of how to use the plugin.
+
+### Other types of documentation
+
+Aside from the four main documentation types, there are a few additional types of documentation found in the Gatsby repo. Check out the following guides for more information:
+
+- [How to Write a Plugin README](/contributing/docs-contributions/how-to-write-a-plugin-readme)
+- [How to Write a Starter README](/contributing/docs-contributions/how-to-write-a-starter-readme)

docs/contributing/docs-contributions/how-to-write-a-conceptual-guide.md

@@ -0,0 +1,30 @@
+---
+title: How to Write a Conceptual Guide
+---
+
+## What is a Conceptual Guide?
+
+A Conceptual Guide provides a big-picture explanation of higher-level Gatsby concepts. Conceptual Guides are most useful for readers who want to build a deeper understanding of a particular topic.
+
+Rather than focusing on specific technical details, Conceptual Guides take a step back to look at the broader picture. For example, it might explain [image optimizations](/docs/conceptual/using-gatsby-image/) or compare [build time and runtime data fetching](/docs/conceptual/data-fetching/).
+
+You can think of a Conceptual Guide as a discussion. It compares the benefits and risks of different approaches. It provides additional historical context to explain how things ended up the way they are.
+
+> For more information on Conceptual Guides, check out the [Divio documentation system](https://documentation.divio.com/explanation/), which the Gatsby docs are based on.
+>
+> **Note:** In the Divio system, these types of docs are called "Explanations" instead of "Conceptual Guides".
+
+## A near-perfect example of a Conceptual Guide
+
+Want to see what a good Conceptual Guide looks like? Check out the [Conceptual Guide: Plugins, Themes, & Starters](/docs/conceptual/plugins-themes-and-starters/).
+
+## Conceptual Guide template
+
+Because of the open-ended nature of a Conceptual Guide, it's difficult to create a template for how to structure one.
+
+Instead, here's a list of questions to consider as you're writing:
+
+- What is the central, underlying concept for this topic? Why is that something worth learning about?
+- What historical background or past decisions would be helpful for newcomers trying to understanding this concept?
+- Are there any other solutions or approaches? What are the pros and cons of each approach?
+- What other viewpoints should be considered?

docs/contributing/docs-contributions/how-to-write-a-how-to-guide.md

@@ -0,0 +1,104 @@
+---
+title: 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](/contributing/docs-contributions/how-to-write-a-reference-guide) or [Conceptual Guide](/contributing/docs-contributions/how-to-write-a-conceptual-guide) and then linking to it in the How-To Guide.
+
+> For more information on How-To Guides, check out the [Divio documentation system](https://documentation.divio.com/how-to-guides/), 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](/docs/how-to/plugins-and-themes/using-a-plugin-in-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.
+
+```markdown
+---
+title: Do Some Task
+---
+
+## Introduction
+
+The introductory paragraph should be a 2-3 sentence explanation of the
+main topic and answer the following questions:
+
+What is the purpose of this guide? What will readers have achieved by
+following the steps in this guide?
+
+Why is this process worth doing? How will it help readers improve their
+Gatsby site?
+
+## Prerequisites
+
+If applicable, list any prerequisites to reading and understanding your
+article.
+
+Does the reader need to read another document first, install a particular
+plugin, or already know a certain skill? List those things here.
+
+## Directions
+
+This section should be a step-by-step list of instructions for how readers
+can achieve the goal.
+
+1. Do the first thing.
+2. Do the next thing.
+
+Use code blocks to show exactly what readers should type. The
+Gatsby Style Guide includes tips for best practices when using code
+blocks:
+https://www.gatsbyjs.com/contributing/gatsby-style-guide/#format-code-blocks-inline-code-and-images
+
+If it's a particularly long list of directions, you can split the steps into
+sections. Use subheadings to label each chunk. For example:
+
+### Step 1: Do the first thing.
+
+1. The first step of the first thing.
+1. The second step of the first thing.
+
+### Step 2: Do some other thing.
+
+1. The first step of some other thing.
+1. The second step of some other thing.
+
+## Additional Resources
+
+Include other resources you think readers would benefit from or next steps
+they might want to take after reading your How-To Guide. You can also
+mention any resources that helped you write the article (blog posts, outside
+tutorials, etc.).
+
+Best-case scenario, these should be high-quality, evergreen
+(not quickly outdated) resources.
+
+- Link to a blog post
+- Link to a YouTube tutorial
+- Link to an example site
+- Link to source code for a live site
+- Links to relevant plugins
+- Links to starters
+```

docs/contributing/how-to-write-a-plugin-readme.md → docs/contributing/docs-contributions/how-to-write-a-plugin-readme.md

@@ -1,8 +1,9 @@
 ---
 title: How to Write a Plugin README
-issue: https://github.com/gatsbyjs/gatsby/issues/21599
 ---
 
+A plugin README is like a Reference Guide for a specific plugin. It should describe what the plugin does, how to install and configure it, and how to use it in your site.
+
 ## Near-perfect example of a plugin README
 
 [`gatsby-source-filesystem`](/plugins/gatsby-source-filesystem/)

docs/contributing/docs-contributions/how-to-write-a-reference-guide.md

@@ -0,0 +1,80 @@
+---
+title: How to Write a Reference Guide
+---
+
+## What is a Reference Guide?
+
+A Reference Guide is a nitty-gritty technical description of how some piece of Gatsby works. Reference Guides are most useful when you need detailed information about Gatsby's APIs or internals.
+
+Reference Guides contain information that many developers would expect to find in technical documentation: function descriptions, parameters and default values, component properties. The Reference Guides section of the docs also includes the [Release Notes](/docs/reference/release-notes/) for each version of Gatsby.
+
+Reference Guides work well for describing the nuts and bolts of how to use a Gatsby feature. You can think of a Reference Guide as an encyclopedia article about a specific plant. It lists details like the plant's defining characteristics, where it can be found, how it can be used. It might also include warnings about potential side effects.
+
+A Reference Guide isn't meant to be read from start to finish. Rather, it's meant to be used by developers who are actively working on a project and need to look up some details about how a particular Gatsby feature works. It might include code examples to show how to use a feature in context, but it doesn't provide a full step-by-step process like what you'd expect from a [How-To Guide](/contributing/docs-contributions/how-to-write-a-how-to-guide) or [Tutorial](/contributing/docs-contributions/how-to-write-a-tutorial)
+
+> For more information on Reference Guides, check out the [Divio documentation system](https://documentation.divio.com/reference-guides/), which the Gatsby docs are based on.
+
+## A near-perfect example of a Reference Guide
+
+Want to see what a good Reference Guide looks like? Check out the [Reference Guide: Gatsby Image plugin](/docs/reference/built-in-components/gatsby-plugin-image/).
+
+## Reference Guide template
+
+The structure of each Reference Guide will be slightly different, but they should have at least the following sections:
+
+- **Introduction:** The first section. Provide some quick background information to help readers understand 1) what this feature is (at a high level) and 2) why it's useful.
+- **Additional Resources:** The last section. Links to other docs or content that might be useful next steps for readers. Also, any resources that helped you write the Reference Guide.
+
+The sections in between the Introduction and Additional Resources should be broken down in a way that best fits the feature you're describing.
+
+You can copy and paste the markdown text below and fill it in with your own information. See the docs contributions guide for information about [structuring accessible headings](/contributing/docs-contributions#headings).
+
+```markdown
+---
+title: Feature Name
+---
+
+## Introduction
+
+In 2-3 sentences, give a high-level description of what this feature does,
+why it's important, and when it might be helpful for users.
+
+## Feature Name
+
+Break up this section into multiple headings, as needed.
+
+Here are some general tips for helpful things to include:
+
+- Diagrams or other visuals, to show key processes or architectures.
+  - Make sure to include alt text for accessibility! For
+    help writing great alt text, refer to the W3C alt decision
+    tree: https://www.w3.org/WAI/tutorials/images/decision-tree/
+- Code examples, to show how to use the feature in practice.
+  - Be sure to include all the necessary imports!
+  - Introduce the code snippet with a sentence describing what the code does
+    and which parts the reader should pay particular attention to.
+  - Code snippets should be as close to real-world examples as possible.
+    Avoid using "foobar" examples.
+- Lists of parameters, including:
+  - A description of what it does
+  - The expected data type
+  - The default value
+- Tips for troubleshooting.
+  - Are there any edge cases that readers should be aware of?
+  - What common error messages might readers encounter? How can they
+    resolve the problem?
+
+## Additional Resources
+
+Include other resources you think readers would benefit from or next steps
+they might want to take after reading your Reference Guide. You can also
+mention any resources that helped you write the article (blog posts, outside
+tutorials, etc.).
+
+- Link to a blog post
+- Link to a YouTube tutorial
+- Link to an example site
+- Link to source code for a live site
+- Links to relevant plugins
+- Links to starters
+```