ContextQMD
Back to Gatsby

How the Docs are Structured

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

2.20.03.5 KB
Original Source

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.

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: