Docs Templates

Docs reference guides, recipes, and tutorials teach Gatsby concepts to users with a variety of learning styles and skill-sets. It’s the Gatsby way of writing learning materials.

Here are some things to keep in mind when deciding where to contribute to Gatsby:

• Blog posts are primarily made for case studies and time-sensitive storytelling.
• Reference guides, in contrast, are evergreen — or continually relevant — and discoverable documentation articles that go beyond any one case study or situation.
• Recipes add concise, discoverable, and easy-to-follow instructions for common Gatsby tasks. They are smaller units than tutorials.
• Tutorials should provide step-by-step guidance for Gatsby workflows, listing all pre-requisites and not assuming knowledge or skipping steps.

Why use templates?

Here are templates (models) to follow when contributing to Gatsby docs to ensure that the docs accomplish their purpose. If you have a good reason to deviate from the following template structures, mention those reasons in the PR so others can give proper feedback.

Reference guides

What are reference guide articles?

Reference guide articles cover discrete topics as documentation with links to other resources. A reference guide explains a Gatsby concept or technique without the step-by-step context provided by a tutorial or recipe.

Reference guide sections provide canonical information on how and why to build things with Gatsby for a variety of scenarios.

What should a reference guide be about?

We need guide articles to describe every concept and task you can accomplish with Gatsby.

Each guide article should explain exactly one concept and that concept should be apparent from the article’s title. Overview guides can list child pages to present multiple ways of getting a job done while limiting the scope of each individual article (e.g. Styling Your Site, Using Layout Components, Standard Global CSS Files, etc.)

Near-perfect example of a reference guide

Linking Between Pages

What if I want to include multiple tasks and concepts in a reference guide?

If you find yourself wanting to include multiple related topics in one article, consider splitting each into its own individual guide and referencing the other topics under sections called “Prerequisites” and/or “Other Resources” sections in the related guide articles.

It’s more ideal to have many articles that cover a broad range of technical topics rather than smashing too many topics into one article.

If you find yourself wanting to teach the reader how to accomplish a series of related tasks, you might want to write a tutorial. For short and super common how-to instructions for a single task, a recipe may work best.

When to write a reference guide vs. a tutorial, vs. a recipe?

Reference guide articles cover discrete topics as documentation while linking to other resources and guides. A reference guide explains a task or concept without the step-by-step context provided by a tutorial or recipe.

Tutorials guide users through a series of related tasks they can string together successfully. Listing prerequisites up front and limiting distractions or links away from the instructions can make a focused tutorial.

Recipes are a happy medium between step-by-step tutorials and crawling the full reference guides, by providing step-by-step guidance for short, common Gatsby tasks. They live in the Recipes section of the docs.

How to choose a reference guide topic?

Guide topics should be chosen based on these priorities:

1. Stub articles (docs that already exist on the site but don’t have content in them yet)
2. Articles with the help wanted and type:documentation labels on GitHub
3. Articles related to improving key learning workflows
4. Articles listed in the “Backlog” or “To prioritize” sections of the Learning / Devrel Roadmap on GitHub
5. Articles that you or other community members would like to see

Length of a reference guide

Ideally, a guide’s table of contents would fit above the fold on a desktop computer screen. This means the outline is easily consumable, so the person can quickly determine if that section of the docs contains the information they need to complete a task.

The content of a reference guide should provide just enough information to be actionable. Linking out to other materials and guides outside of Gatsby’s core concepts is recommended to limit the scope to critical and unique parts of Gatsby development.

Reference guide template

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.

Reference guide overview

Near-perfect example of a guide overview

Deploying and Hosting

What should a reference guide overview be about?

Each overview should give a short introduction of its section of the guides and list the relevant subtopics.

Length of a reference guide overview

Ideally, a guide overview fits above the fold on a desktop computer screen. This means the outline is easily consumable, so the person can quickly determine if that section of the docs contains the information they need to complete a task.

When should I create a new reference guide overview?

Guide overview articles are essentially new parent categories that help organize all the reference guides. Here’s how to decide if you should create a new reference guide overview:

1. Stub articles (docs that already exist on the site but don’t have content in them yet)
2. Article sections with the help wanted and type:documentation labels on GitHub
3. Article sections related to improving key learning workflows, like “e-commerce”
4. Article sections listed in the “Backlog” or “To prioritize” sections of the Learning / Devrel Roadmap on GitHub
5. Article sections that you or other community members would like to see

Reference guide overview template

You can copy and paste the markdown text below and fill it in with your own information

Recipes

Docs Recipes should act as discoverable, concise instructions for completing common Gatsby tasks without having to navigate elsewhere. They live on the Recipes page in the docs, the source of which can be found in docs/docs/recipes.md in the GitHub repo.

A recipe should list requirements and include a few short instructions to complete a task. It should omit boilerplate and list only directly related, actionable instructions inline. Recipes are smaller units than tutorials, each limited to a single feature or task. Multiple recipes could be linked from a reference guide or tutorial, however the content should be consolidated in the Recipes section for discoverability. If a recipe is recorded as a video, it should be less than five or ten minutes long.

The components of a recipe are:

• The name of the recipe, which should describe a single task
• A 1-2 sentence description motivating what the recipe is for
• Prerequisites and requirements
• Step-by-step directions
  • 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.

If you’re finding a recipe is becoming too long to fit on the Docs Recipes page due to including many prerequisites or steps, consider writing a tutorial instead.

Recipe categories

Grouping recipes by topic will allow users to navigate and learn by subject matter. As recipes following the new format are introduced, you might find a section needs an h2 heading added for the group. The older-style recipes should be gradually replaced with actionable recipes following the template below.

Recipes should fall into these categories to start (suggest your idea in a GitHub issue!):

• Pages/Layouts
• Styling
• Using a starter
• Using themes
• Sourcing data
• Querying data
• Images
• Transforming data
• Deploying

Here’s a template for a new recipe category:

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:

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.

Tutorials

In contrast to recipes and reference guides, tutorials are step-by-step instructions for a series of related Gatsby tasks. Tutorials are grouped into Gatsby Fundamentals and Intermediate Tutorials (“The Gatsby Tutorial”), as well as Advanced Tutorials which can be explored individually as needed.

Near perfect example of a tutorial

Main Gatsby tutorial

What should a tutorial be about?

We need tutorials to guide users of all skill levels through performing a series of related tasks with Gatsby.

How to choose a tutorial topic?

Topics should be chosen based on these priorities:

1. Tutorials related to improving key learning workflows
2. Tutorials listed in the “Backlog” or “To prioritize” sections of the Learning / Devrel Roadmap on GitHub
3. Tutorials with the help wanted and type:documentation labels on GitHub
4. Tutorials that you or other community members would like to see

Length of a tutorial

If a tutorial is longer than 3 8.5x11” pages or has more than about 5 headers and you’re finding yourself creating a Table of Contents at the top, it will probably be easier to read and easier for readers to complete if you turn it into a multi-page tutorial, like the main Gatsby tutorial.

If you have a tutorial that falls into this category, it is likely a big enough project that you’ll benefit from the feedback process provided by creating an RFC (Request for Comments) document.

Tutorial template

You can copy and paste the markdown text below and fill it in with your own information.

Plugin README template

Near-perfect example of a plugin README

gatsby-source-filesystem

Starter README template

Near-perfect example of a starter README

Default Starter README