Docs Writing Process
When a new feature or integration is released that Gatsby developers can take advantage of, documentation should be added to improve the learning experience. Gatsby also needs docs for topic areas that exist in other technologies but are under-documented or under-tooled in the Gatsby ecosystem.
The knowledge of how to work with a technique, source plugin, or varied use case may be known internally to Gatsby team members, but it also may only exist on the web at large. This contributing doc is intended to provide a written process for producing docs without prior information, a critical function of the Gatsby Documentation team and open source community.
Identifying a topic
When identifying a topic, start by:
Looking at GitHub issues. Good labels to seek out are
help wantedandgood first issue.- This part may be covered if a docs issue is assigned to you, or if you’re signing up voluntarily to take on an issue.
Look at the stub list to find docs that need contributions.
Look at the learning workflow meta issue to find active areas looking for docs.
Read through the existing Gatsby docs information and find gaps in topic coverage. Is there an area you feel is missing? File an issue to discuss it. If the team determines it warrants documentation, implement in a PR.
Observe common points of confusion or rough edges through user feedback and recommend solutions.
Note: It’s required to open a GitHub issue before submitting a PR if one does not already exist.
Selecting the correct format
A GitHub issue for new learning material should indicate the format. Is it a Reference or Conceptual Guide? A Tutorial? A recipe?
Does docs coverage exist anywhere on gatsbyjs.com? If so, would an alternative format help provide information for Gatsby learners of different skill and experience levels? For example, if a tutorial exists but there is no coverage in Reference Guides, adding more content in a different format would benefit users.
Tutorials vs. recipes vs. guides:
- Tutorials are step-by-step learning materials that show a user how to do something without skipping steps. Tutorials must consider a beginner experience, but can be useful for anyone.
- Recipes are shorter, more concise tutorials that limit their scope to a single task or outcome by using prerequisites and limited steps. Additional resources at the end lead the user to a logical next step. Recipes are for developers of all skill levels.
- Guides are different than tutorials, and the two main sections are Reference Guides and Conceptual Guides. Instead of “steps 1-4”, guides use standalone headings and sections to explain how to accomplish the task. They are often aimed at a more advanced audience due to the subject matter but should be approachable to anyone.
Given the difference in audiences of the three main learning material formats, increasing and overlapping coverage of topics can help support Gatsby learners of different skill and experience levels.
Please follow the Gatsby blog post guidelines and do not suggest blog posts when what is needed is user documentation.
More on the format of documentation and learning materials can be found in the contributing docs:
Gathering and validating supporting information
Writing an effective doc that meets the needs of Gatsby users requires gathering information from various sources and applying those concepts to your original writing. You must digest and validate the details you uncover and understand them enough to describe them in a way that users of multiple skill levels can learn.
Here are some tips for gathering information on a given topic within Gatsby:
As you prepare a contribution that adds documentation information, carefully read the accompanying GitHub issue for tips and relevant materials, and ask questions there.
Search the Gatsby GitHub repo for additional tips, examples, starters, plugins, READMEs, and other information that could help you provide a learning resource that guides users through a particular use case or concept.
You can also search the web for additional examples outside of the Gatsby GitHub org or docs site. Be sure to check Gatsby versions and only reference the most current examples unless for a specific purpose.
In the event there is no information available to write a greenfield doc after trying all the above steps, such as for a new integration, try interviewing Gatsby core team members to help to produce an outline and content tips. See Pair Programming program.
For Gatsby inkteam members: You can also search in the Gatsby Slack internally for related information. It’s possible other team members have discussed the issue, or even compiled trouble points into a doc. Look and ask around as part of your discovery work.
After you’ve collected supporting information, you must produce original writing to be accepted in the Gatsby docs. Copying other blog posts, materials, or Gatsby team member interviews word-for-word without attribution is not acceptable or allowed. Furthermore, direct quotes from interviews are also almost never effective for guides, recipes, or tutorials.
Rather, the best way to write greenfield docs is with new text that explains the concepts and ideas you uncovered. With research and demos supporting your writing, you can speak more legitimately to use cases and common troubleshooting. Phrasing information in alternative ways for different skill levels is a bit like avoiding usage of the same word or phrase in its definition: if a reader didn’t understand it the first time, they may be more likely to understand it with an alternative explanation.
Producing learning materials
Create demo sites and examples to provide more authoritative material that supports the developer experience. When relevant, functioning source code is a requirement to writing docs that truly educate users. Source code examples can also be linked from a doc as an additional resource. Include testing as part of your source code to ensure it is robust and stands the test of time.
Follow the docs templates to ensure you’re producing content in the right format for its purpose.
Use the Markdown syntax doc to understand your options for formatting text with Markdown, and follow accessibility recommendations for heading levels and image alt text.
Run the docs site locally to check formatting and functionality. There are instructions in the contributing docs.
Refer to the Gatsby style guide to ensure your PR will be accepted.
Submitting a pull request
Submit a pull request that’s tied to a GitHub issue by following the How to Open a Pull Request guide.
Apply feedback from pull request reviews in order for them to be accepted. Further instructions can be found in the How to Open a Pull Request guide.