Docs Templates

Docs reference guides, recipes, and tutorials teach Gatsby concepts to users with a variety of learning styles and skill-sets. It’s the Gatsby way of writing learning materials.

Here are some things to keep in mind when deciding where to contribute to Gatsby:

• Blog posts are primarily made for case studies and time-sensitive storytelling.
• Reference guides, in contrast, are evergreen — or continually relevant — and discoverable documentation articles that go beyond any one case study or situation.
  • Other guides add documentation for specific purposes like the API reference, Conceptual Guide, Gatsby Internals, and more.
• Recipes add concise, discoverable, and easy-to-follow instructions for common Gatsby tasks. They are smaller units than tutorials.
• Tutorials should provide step-by-step guidance for Gatsby workflows, listing all pre-requisites and not assuming knowledge or skipping steps.

When writing (or reviewing) learning materials that show Gatsby users how to complete tasks, you are expected to test out any code examples or steps to ensure they work. This can also help with writing in your own words, rather than copying from other sources. If you have a demo project or code example that strengthens docs and you don’t know where to put it, mention it to the Gatsby Documentation team in a PR.

Why use templates?

Follow the how-to templates (models) listed here when contributing to Gatsby docs to ensure that the docs accomplish their purpose. If you have a good reason to deviate from the following template structures, mention those reasons in an issue so others can give proper feedback on your idea.