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.
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:
- How to Write a How-To Guide
- How to Write a Reference Guide
- How to Write a Conceptual Guide
- How to Write a Tutorial
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:
- Gatsby Image plugin: A Reference Guide to explain the plugin API and all its options.
- Using the Gatsby Image plugin: A How-To Guide to show practical examples of how to use the plugin.
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: