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 includes four different types of materials. Each one is tailored to meet a specific user need.

  • How-To Guides 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 are nitty-gritty technical descriptions of how Gatsby works. These are most useful when readers need detailed information about Gatsby’s APIs.
  • Conceptual Guides 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 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.

This documentation structure is based on the Diátaxis documentation system 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:

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:

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:

Edit this page on GitHub