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.
- Other guides add documentation for specific purposes like the API reference, Conceptual Guide, Gatsby Internals, and more.
- 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.
When writing (or reviewing) learning materials that show Gatsby users how to complete tasks, you are expected to test out any code examples or steps to ensure they work. This can also help with writing in your own words, rather than copying from other sources. If you have a demo project or code example that strengthens docs and you don’t know where to put it, mention it to the Gatsby Learning team in a PR.
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 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. Reference material should list text headings for each section of a guide, rather than “steps 1-5” like a tutorial.
The Gatsby docs include multiple types of guides. They mostly follow the same format, but some docs will have a slightly different purpose and/or audience.
- Reference Guides: explanations of Gatsby site development techniques and common workflows. These should be written for all skill-levels.
- API Reference: technical docs on API methods and options, common files, and links to additional resources and explanations.
- Releases & Migration: release notes and guides on how to upgrade Gatsby and third-party packages.
- Conceptual Guides: high-level docs to explain important Gatsby concepts and philosophies.
- As an example, “Plugins, Themes, and Starters” would be an overarching concept article, with individual reference guide sections for Plugin, Theme, and Starter docs.
- Gatsby Internals: previously titled Behind the Scenes, these docs go in depth into how Gatsby works under the hood.
- Using Gatsby Professionally: articles on winning over stakeholders, working in larger organizations, and building a career as a Gatsby developer.
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.)
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.
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.
Guide topics should be chosen based on these priorities:
- Stub articles (docs that already exist on the site but don’t have content in them yet)
- Articles with the help wanted and type:documentation labels on GitHub
- Articles related to improving key learning workflows
- Articles listed in the “Backlog” or “To prioritize” sections of the Learning / Devrel Roadmap on GitHub
- Articles that you or other community members would like to see
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.
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.
Each overview should give a short introduction of its section of the guides and list the relevant subtopics.
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.
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:
- Stub articles (docs that already exist on the site but don’t have content in them yet)
- Article sections with the help wanted and type:documentation labels on GitHub
- Article sections related to improving key learning workflows, like “e-commerce”
- Article sections listed in the “Backlog” or “To prioritize” sections of the Learning / Devrel Roadmap on GitHub
- Article sections that you or other community members would like to see
You can copy and paste the markdown text below and fill it in with your own information
Docs Recipes should act as discoverable, concise instructions for completing common Gatsby tasks without having to navigate elsewhere. They live in the Recipes section in the docs, the source of which can be found in the
docs/docs/recipes.md landing page and
docs/docs/recipes/* folder 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:
- Overview link on
- 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.
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!):
- Using a starter
- Using themes
- Sourcing data
- Querying data
- Transforming data
Here’s a template for a new recipe category:
To make sure your recipe is linked from the overview page, you must add it to the appropriate category in
recipes.md. Otherwise, it will be difficult for Gatsby users to find it, which isn’t good for anyone!
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.
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”).
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.
This is the place to link to related docs, tutorials, and additional examples.
When writing a recipe, try to include each of the below items wherever relevant.
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.
We need tutorials to guide users of all skill levels through performing a series of related tasks with Gatsby.
Topics should be chosen based on these priorities:
- Tutorials related to improving key learning workflows
- Tutorials listed in the “Backlog” or “To prioritize” sections of the Learning / Devrel Roadmap on GitHub
- Tutorials with the help wanted and type:documentation labels on GitHub
- Tutorials that you or other community members would like to see
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.
You can copy and paste the markdown text below and fill it in with your own information.