How to Write a Tutorial
The Gatsby Tutorial is a self-contained introduction that guides readers step-by-step through creating their first Gatsby site. The Tutorial is most useful when readers are first getting started with Gatsby.
By following the steps in a Gatsby tutorial, a user should:
- Experience the value of Gatsby as quickly as possible. With Gatsby, a user typically values that it takes fewer steps (and is therefore easier) to:
- start coding immediately without being an expert
- start a new project
- make edits and see them through hot reloading
- publish a site
- do basic tasks like create pages, link between pages, create routing, change styles
- Know how to and actually start and deploy a site as quickly as possible.
- Be able to share their site.
- Know how to and actually find more advanced tutorials and docs.
- Use enough React to do basic tasks like creating pages, links, styles.
- Have fun!
Through research, it’s clear that developers of all skill levels read the main Gatsby tutorial and go back to reference it later.
Additional tutorials provide supplemental learning content for more Gatsby workflows as well as opportunities for members of the Gatsby community to contribute to the docs.
Gatsby tutorials should prioritize helping users with the following attributes and goals.
- new to React and interested in it
- new to Gatsby and interested in it
- proficient with browsers and operating system basics
- a way to learn and/or improve React skills
- a way to start a site and/or app project that uses React
The tone and style of a Gatsby tutorial should effectively help the audience reach their goals.
The main tutorial ought to use the same personal “you” like the rest of the docs; in addition, the tutorial ought to use a warm, validating tone by congratulating users, complimenting them, and generally saying things like “yay!” more often.
Because the audience of the tutorial is people who do not consider themselves experts in React, it’s important to reduce the amount of new information to bare minimum. The goal: give people only the information necessary to complete a task and to know how to repeat the task again, outside of the context of the tutorial.
In practice, you can reach this goal by two rules of thumb:
- Reduce the number of hyperlinks, tabs, and environments to the least number required to complete the tasks in the tutorial.
- When there are multiple ways to complete a task, give people only one way. This way ought to be the best practice possible within the constraints of the lowest supported versions of software. If the best practice isn’t possible with the lowest supported versions of software, mention that as a side note.
You can copy and paste the markdown text below and fill it in with your own information.