How to Write a Reference Guide

What is a Reference Guide?

A Reference Guide is a nitty-gritty technical description of how some piece of Gatsby works. Reference Guides are most useful when you need detailed information about Gatsby’s APIs or internals.

Reference Guides contain information that many developers would expect to find in technical documentation: function descriptions, parameters and default values, component properties. The Reference Guides section of the docs also includes the Release Notes for each version of Gatsby.

Reference Guides work well for describing the nuts and bolts of how to use a Gatsby feature. You can think of a Reference Guide as an encyclopedia article about a specific plant. It lists details like the plant’s defining characteristics, where it can be found, how it can be used. It might also include warnings about potential side effects.

A Reference Guide isn’t meant to be read from start to finish. Rather, it’s meant to be used by developers who are actively working on a project and need to look up some details about how a particular Gatsby feature works. It might include code examples to show how to use a feature in context, but it doesn’t provide a full step-by-step process like what you’d expect from a How-To Guide or Tutorial

For more information on Reference Guides, check out the Diátaxis documentation system, which the Gatsby docs are based on.

A near-perfect example of a Reference Guide

Want to see what a good Reference Guide looks like? Check out the Reference Guide: Gatsby Image plugin.

Reference Guide template

The structure of each Reference Guide will be slightly different, but they should have at least the following sections:

• Introduction: The first section. Provide some quick background information to help readers understand 1) what this feature is (at a high level) and 2) why it’s useful.
• Additional Resources: The last section. Links to other docs or content that might be useful next steps for readers. Also, any resources that helped you write the Reference Guide.

The sections in between the Introduction and Additional Resources should be broken down in a way that best fits the feature you’re describing.

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.