How to Write a Conceptual Guide

What is a Conceptual Guide?

A Conceptual Guide provides a big-picture explanation of higher-level Gatsby concepts. Conceptual Guides are most useful for readers who want to build a deeper understanding of a particular topic.

Rather than focusing on specific technical details, Conceptual Guides take a step back to look at the broader picture. For example, it might explain image optimizations or compare build time and runtime data fetching.

You can think of a Conceptual Guide as a discussion. It compares the benefits and risks of different approaches. It provides additional historical context to explain how things ended up the way they are.

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

Note: In the Diátaxis system, these types of docs are called “Explanations” instead of “Conceptual Guides”.

A near-perfect example of a Conceptual Guide

Want to see what a good Conceptual Guide looks like? Check out the Conceptual Guide: Plugins, Themes, & Starters.

Conceptual Guide template

Because of the open-ended nature of a Conceptual Guide, it’s difficult to create a template for how to structure one.

Instead, here’s a list of questions to consider as you’re writing:

• What is the central, underlying concept for this topic? Why is that something worth learning about?
• What historical background or past decisions would be helpful for newcomers trying to understand this concept?
• Are there any other solutions or approaches? What are the pros and cons of each approach?
• What other viewpoints should be considered?