docs: misc feedback improvements (#15236)

* fix: add more details to recipes template

* fix: add link to auth tutorial from Gatsby Link

* fix: correction in testing components doc

* fix: add mention of npx in Quick Start

* fix: add notes about accessible headings in docs

* fix: remove note about npx, reshooting video

* fix: update recipes page with new format

* fix: remove bit about KPIs to keep the doc focused

* fix: update Style Guide for new docs formats

docs/contributing/docs-contributions.md

@@ -9,6 +9,7 @@ On this page:
 - [Top priorities](#top-priorities)
 - [Options for contributing to the Gatsby docs](#options-for-contributing-to-the-gatsby-docs)
 - [Fixing image and link paths](#fixing-image-and-link-paths)
+- [Headings](#headings)
 - [Modifying markdown files](#modifying-markdown-files)
   - [Converting a document from a stub](#converting-a-document-from-a-stub)
 - [Docs site setup instructions](#docs-site-setup-instructions)
@@ -37,6 +38,12 @@ To address missing images, check the doc or tutorial source [in the Gatsby repo]
 
 If you find a broken link in the Gatsby docs, feel free to fix it and submit a PR!
 
+## Headings
+
+Docs with frontmatter metadata at the top including a `title` will automatically receive an `<h1>` heading in the rendered page, and it should be the only one. Additional headings in docs content should start with `<h2>`, denoted by `##` in Markdown.
+
+For the purposes of an accessible document outline, content headings should go in order from h2-h4 (`####`) until all levels have been established. This will ensure the Gatsby docs have a content hierarchy that works well for users of assistive technology. Read more about the importance of [headings and semantic structure in HTML](https://webaim.org/techniques/semanticstructure/).
+
 ## Modifying markdown files
 
 1. If you want to add/modify any Gatsby documentation, go to the

docs/contributing/docs-templates.md

@@ -80,7 +80,7 @@ The content of a reference guide should provide just enough information to be ac
 
 ### Reference guide template
 
-You can copy and paste the markdown text below and fill it in with your own information
+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
 ---
@@ -202,9 +202,11 @@ A recipe should list requirements and include a few short instructions to comple
 The components of a recipe are:
 
 - The name of the recipe, which should describe a single task
-- A list of requirements and prerequisites
+- A 1-2 sentence description motivating what the recipe is for
+- Prerequisites and requirements
 - Step-by-step directions
-- A link to a working example
+  - Optional embedded examples
+- Links to additional resources
 
 Recipes should be short. This is accomplished by limiting steps to what is unique to the task at-hand; prerequisites and requirements should be mentioned but not include install steps for things like npm or Gatsby CLI. Linking to full reference guide, tutorial, or a working example can complete the loop for anyone who needs more help.
 
@@ -226,20 +228,51 @@ Recipes should fall into these categories to start (suggest your idea in a GitHu
 - Transforming data
 - Deploying
 
-Here's a template for a recipe category:
+Here's a template for a new recipe category:
 
 ```markdown:title=docs/docs/recipes.md
 ## Category name
 ```
 
+### Recipe parts
+
+#### Title and description
+
+To help motivate the purpose of a recipe, its title should clearly indicate the task being covered; not just the tool or API being used. E.g. "Using the StaticQuery Component" is more descriptive than "StaticQuery".
+
+Descriptions should be 1-2 sentences long and expand on the title to further motivate why someone would want to follow this recipe.
+
+#### Prerequisites
+
+Each recipe should include 2-5 requirements or prerequisites, some of which may not be explicitly required but are good to be aware of. These items should list any steps that must be done or checked before starting the recipe to keep it focused and succinct.
+
+Each prerequisite should include only the _item_ or _thing_ needed, not the whole step (verbs like "installed").
+
+Prerequisites example:
+
+```markdown
+- React and ReactDOM 16.8.0 or later (keeping Gatsby updated handles this)
+- The [Rules of React Hooks](https://reactjs.org/docs/hooks-rules.html)
+```
+
+#### Directions
+
+The steps should list each part of the task in detail (omitting unrelated boilerplate or installation steps), and not skip or gloss over necessary details. Typically these steps are included with an ordered list. It's subjective whether to include a code snippet for each step, and will require your best judgement (ask for help in a PR if you're not sure). For some recipes, listing each individual step in text and including a single code snippet for the recipe makes sense to keep it short.
+
+If a recipe issue recommends a live example such as a CodeSandbox embed, the recipe steps are the best place to include it.
+
+#### Additional resources
+
+This is the place to link to related docs, tutorials, and additional examples.
+
 ### Recipe template
 
 When writing a recipe, try to include each of the below items wherever relevant.
 
 ````markdown:title=docs/docs/recipes.md
 ### Recipe name
 
-#### Requirements
+#### Prerequisites
 
 - A Gatsby site with two page components: `index.js` and `contact.js`
 - The Gatsby <Link /> component
@@ -266,10 +299,10 @@ export default () => (
 2. Run `gatsby develop` and navigate to the index page. You should have a link
    that takes you to the contact page when clicked!
 
-#### Related links
+#### Additional resources
 
-- Any live demos
-- Other materials to check out
+- Related docs/materials to check out
+- Any other demos
 ````
 
 ## Tutorials

docs/contributing/gatsby-style-guide.md

@@ -36,11 +36,15 @@ The community plans, writes, and maintains these Docs on GitHub.
 - [Best practices](#best-practices)
   - [Support software versions](#software-versions)
   - [Share best practices whenever possible](#share-best-practices-whenever-possible)
-- [The difference between tutorials and docs](#the-difference-between-tutorials-and-docs)
-- [Tutorial](#tutorial)
-  - [Tutorial Audience](#tutorial-audience)
-  - [Tutorial Purpose](#tutorial-purpose)
-  - [Tutorial Tone and style](#tutorial-tone-and-style)
+- [The difference between tutorials, recipes, and docs](#the-difference-between-tutorials-recipes-and-docs)
+- [Tutorials](#tutorials)
+  - [Tutorials Audience](#tutorials-audience)
+  - [Tutorials Purpose](#tutorials-purpose)
+  - [Tutorials Tone and style](#tutorials-tone-and-style)
+- [Recipes](#recipes)
+  - [Recipes Audience](#recipes-audience)
+  - [Recipes Purpose](#recipes-purpose)
+  - [Recipes Tone and style](#recipes-tone-and-style)
 - [Docs](#docs)
   - [Docs Audience](#docs-audience)
   - [Docs Purpose](#docs-purpose)
@@ -64,11 +68,12 @@ Before you begin writing, make sure to read the rest of this style guide.
 Docs can cover a broad range of topics. Please see the following
 examples:
 
-- [guides](/docs/add-404-page/)
-- [guide overviews](/docs/styling/)
-- [tutorials](/tutorial/part-one/)
-- [plugin README](/packages/gatsby-source-filesystem/)
-- [starter README](https://github.com/gatsbyjs/gatsby-starter-default)
+- [Reference guides](/docs/add-404-page/)
+- [Reference guide overviews](/docs/styling/)
+- [Recipes](/docs/recipes/)
+- [Tutorials](/tutorial/part-one/)
+- [Plugin README](/packages/gatsby-source-filesystem/)
+- [Starter README](https://github.com/gatsbyjs/gatsby-starter-default)
 
 Please see the [Docs templates](/contributing/docs-templates/) for guidelines on how to format the above kinds of documents.
 
@@ -446,17 +451,19 @@ When there are multiple ways to complete a task, the docs should explain the fol
 
 For example, `gatsby-image` is a component that includes Gatsby best practices for handling images, yet there are more fundamental and common ways of handling them. Documentation ought to make the best practice clear in addition to the most common and fundamental ways.
 
-## The difference between tutorials and docs
+## The difference between tutorials, recipes, and docs
 
 The main tutorial at `/tutorial/` is optimized for users who are not experts in React and/or JavaScript, and therefore has a different purpose, tone, and style than the docs. The docs at `/docs/` are optimized for those with intermediate to expert mastery with React and JavaScript.
 
-## Tutorial
+## Tutorials
 
-### Tutorial audience
+### Tutorials audience
 
-Through research, it's clear that developers of all skill levels read the tutorial and go back to reference it later.
+Through research, it's clear that developers of all skill levels read the main Gatsby tutorial and go back to reference it later.
 
-The tutorial should prioritize helping users with the following attributes and goals.
+Additional tutorials provide supplemental learning content for more Gatsby workflows as well as opportunities for members of the Gatsby community to contribute to the docs.
+
+Gatsby tutorials should prioritize helping users with the following attributes and goals.
 
 Attributes:
 
@@ -470,14 +477,14 @@ Looking for:
 - a way to learn and/or improve React skills
 - a way to start a site and/or app project that uses React
 
-### Tutorial purpose
+### Tutorials purpose
 
-By following the steps in the tutorial, a user should:
+By following the steps in a Gatsby tutorial, a user should:
 
 - Experience the value of Gatsby as quickly as possible. With Gatsby, a user typically values that it takes fewer steps (and is therefore easier) to:
   - start coding immediately without being an expert
   - start a new project
-  - make edits and see them thru hot reloading
+  - make edits and see them through hot reloading
   - publish a site
   - do basic tasks like create pages, link between pages, create routing, change styles
 - Know how to and actually start and deploy a site as quickly as possible.
@@ -486,9 +493,9 @@ By following the steps in the tutorial, a user should:
 - Use enough React to do basic tasks like creating pages, links, styles.
 - Have fun!
 
-### Tutorial tone and style
+### Tutorials tone and style
 
-The tone and style of the tutorial should effectively help the audience reach their goals.
+The tone and style of a Gatsby tutorial should effectively help the audience reach their goals.
 
 ### Use personal "you" and be warm
 
@@ -505,8 +512,39 @@ In practice, you can reach this goal by two rules of thumb:
 - Reduce the number of hyperlinks, tabs, and environments to the least number required to complete the tasks in the tutorial.
 - When there are multiple ways to complete a task, give people only one way. This way ought to be the best practice possible within the constraints of the lowest supported versions of software. If the best practice isn't possible with the lowest supported versions of software, mention that as a side note.
 
+## Recipes
+
+### Recipes audience
+
+Recipes 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.
+
+### Recipes purpose
+
+Recipes provide concise step-by-step instructions for common Gatsby tasks. Each recipe should include a title, 1-2 sentence description motivating why the recipe is important, a list of prerequisites, steps to complete the task including an optional live example, and any additional references.
+
+### Recipes tone and style
+
+Recipes are shorter and more concise than tutorials 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 a recipe task, anticipating any new or difficult concepts with links to additional materials to continue learning.
+
 ## Docs
 
+"Docs" in Gatsby generally refers to the following sections:
+
+- Quick Start
+- Recipes
+- Reference Guides
+- Gatsby API
+- Releases & Migration
+- Conceptual Guide
+- Gatsby Internals
+- Using Gatsby Professionally
+- Contributing
+- Partnering with Gatsby
+- Commands (Gatsby CLI)
+- Cheat Sheet
+- Glossary
+- Gatsby REPL
+
 ### Docs audience
 
 Developers of all skill levels read the docs and find them useful.
@@ -546,6 +584,7 @@ By referencing the docs, a user should:
   - portfolio
   - e-commerce
   - authenticated
+  - accessible
 
 ### Docs tone and style
 
@@ -564,23 +603,6 @@ In practice, you can reach this goal by two general rules:
 - Include an "additional information" section at the bottom of each guide with hyperlinks to relevant external blogposts, tutorials, and other Gatsby resources and docs.
 - When there are multiple ways to complete a task, [follow these instructions](#share-best-practices-whenever-possible).
 
-## KPIs
-
-Here is how we measure the quality of the tutorial and docs. We will use ([cohort analysis](https://www.geckoboard.com/learn/kpi-examples/mobile-app-kpis/retention-rate/) to track improvements or regressions to the tutorial and docs.
-
-### Tutorial
-
-- time to value: how quickly, effectively, and painlessly can users experience the value of Gatsby?
-- daily, weekly, monthly active users
-- daily, weekly, monthly “finishers” of the tutorial (finishers = people who spend 5 mins minimum on each page of tutorial and go through whole thing)
-- weekly retention rate
-
-### Docs
-
-- time to task: how quickly and effectively can users accomplish tasks?
-- daily, weekly, monthly active users
-- weekly retention rate
-
 ## Why we chose GitHub for writing and maintaining docs
 
 The way the Gatsby community maintains docs and tutorials must meet the following requirements:

docs/docs/gatsby-link.md

@@ -372,3 +372,7 @@ onClick = () => {
   navigate('?foo=bar');
 }
 ```
+
+## Additional resources
+
+- [Authentication tutorial for client-only routes](/tutorial/authentication-tutorial/)

docs/docs/quick-start.md

@@ -56,8 +56,10 @@ gatsby serve
 
 Gatsby starts a local HTML server for testing your built site. Remember to build your site using `gatsby build` before using this command.
 
-### Access documentation for CLI commands.
+### Access documentation for CLI commands
 
 To see detailed documentation for the CLI commands, run `gatsby --help` in the terminal.
 
 For specific commands, run `gatsby COMMAND_NAME --help` e.g. `gatsby new --help`.
+
+For more information on the Gatsby CLI, visit the [CLI reference](/docs/gatsby-cli/) section of the docs.

docs/docs/recipes.md

@@ -5,11 +5,30 @@ title: Recipes
 <!-- Basic template for a Gatsby recipe:
 
 ## Task to accomplish.
+1-2 sentences about it. The more concise and focused, the better!
 
-1-2 sentences about it.
-Relevant links out (tutorial, doc pages, plugin readmes, etc). -->
+### Prerequisites
+- System/version requirements
+- Everything necessary to set up the task
+- Including setting up accounts at other sites, like Netlify
+- See [docs templates](/docs/docs-templates/) for formatting tips
 
-Craving a happy medium between doing the [full tutorial](/tutorial/) and crawling the [full docs](/docs/)? Here's a quick guiding reference for how to build things, Gatsby style.
+### Step-by-step directions
+Each step should be repeatable and to-the-point. Anything not critical to the task should be omitted.
+
+#### Live example (optional)
+A live example may not be possible depending on the nature of the recipe, in which case it is fine to omit.
+
+### Additional resources
+- Tutorials
+- Docs pages
+- Plugin READMEs
+- etc.
+
+See [docs templates](/docs/docs-templates/) in the contributing docs for more help.
+-->
+
+Craving a happy medium between [full-length tutorials](/tutorial/) and crawling the [docs](/docs/)? Here's a cookbook of guiding recipes on how to build things, Gatsby style.
 
 ## Table of Contents
 
@@ -56,11 +75,11 @@ You can create pages in Gatsby explicitly by defining React components in `src/p
 
 Routing in Gatsby relies on the `<Link />` component.
 
-### Requirements
+### Prerequisites
 
 - A Gatsby site with two page components: `index.js` and `contact.js`
 - The Gatsby `<Link />` component
-- `gatsby develop`
+- The [Gatsby CLI](/docs/gatsby-cli/) to run `gatsby develop`
 
 ### Directions
 

docs/docs/testing-components-with-graphql.md

@@ -64,7 +64,7 @@ beforeEach(() => {
 
 describe("Index", () =>
   it("renders correctly", () => {
-    const tree = renderer.create(<BlogIndex />).toJSON()
+    const tree = renderer.create(<Index />).toJSON()
     expect(tree).toMatchSnapshot()
   }))
 ```