(sync) Sync with gatsby-i18n-source @ 8ff6bb0

docs/contributing/blog-and-website-contributions.md → docs/contributing/blog-contributions.md

@@ -1,21 +1,10 @@
 ---
-title: Blog & Website Contributions
+title: Blog Contributions
 ---
 
-We wholeheartedly welcome contributions to the Gatsby blog and website!
+If you'd like to contribute a post to the Gatsby blog, please review the process and guidelines outlined below and submit your idea for the post to our [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF)
 
-Here are some things to keep in mind when deciding where to contribute to Gatsby:
-
-- [Blog posts](#contributing-to-the-blog) work best for case studies and time-sensitive storytelling (see the [blog post format](#blog-post-format)).
-- [Docs](/contributing/docs-contributions/) are continually relevant and discoverable learning materials that go beyond any one case study or situation.
-- [Website changes](#making-changes-to-the-website) that improve either of these are always welcome!
-
-## Contributing to the blog
-
-If you'd like to contribute a post to the Gatsby blog, please review the process and guidelines outlined below and submit your
-idea for the post to our [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF)
-
-### Blog proposal submission process
+## Blog proposal submission process
 
 1. Complete and submit the [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF).
 2. A Gatsby team member will review your proposal and let you know if the proposal has been accepted within the next week or so.
@@ -24,7 +13,7 @@ idea for the post to our [Gatsby blog proposal form](https://airtable.com/shr344
 
 If you have any questions about the process or your submission, please email [[email protected]](mailto:[email protected]).
 
-### Content guidelines for submitting a blog post proposal
+## Content guidelines for submitting a blog post proposal
 
 As a Gatsby community member, you have unique insight into the ins and outs of learning Gatsby, building with Gatsby, and contributing to Gatsby’s open source community. Contributing to the Gatsby blog is a great way to share your experiences and insights. Here are some guidelines for what kind of content is and isn’t a good fit for the Gatsby blog.
 

docs/contributing/code-contributions.md

@@ -12,6 +12,7 @@ On this page:
 - [Contributing example sites](#contributing-example-sites)
 - [Using Docker to set up test environments](#using-docker-to-set-up-test-environments)
 - [Development tools](#development-tools)
+- [Official theme development](#official-theme-development)
 
 ## Repo setup
 
@@ -21,7 +22,7 @@ To start setting up the Gatsby repo on your machine using git, Yarn and Gatsby-C
 
 Alternatively, you can skip the local setup and [use an online dev environment](/contributing/using-an-online-dev-environment/).
 
-To contribute to the blog or Gatsbyjs.org website, check out the setup steps on the [blog and website contributions](/contributing/blog-and-website-contributions/) page. For instructions on contributing to the docs, visit the [docs contributions page](/contributing/docs-contributions/).
+To contribute to the blog, check out the setup steps on the [blog contributions](/contributing/blog-contributions/) page. For instructions on contributing to the docs, visit the [docs contributions page](/contributing/docs-contributions/). To contribute to the website, see the [website contributions](/contributing/website-contributions/) page.
 
 ## Creating your own plugins and loaders
 
@@ -119,6 +120,22 @@ Using Docker Compose, you can start and stop a WordPress instance and integrate
 
 Check [Debugging the build process](/docs/debugging-the-build-process/) page to learn how to debug Gatsby.
 
+## Official theme development
+
+This section is for official theme development in Gatsby's monorepo. If you are looking
+to build your own theme, see [building themes](/docs/themes/building-themes/).
+
+Before getting started, make sure that you have
+[set up your local dev environment](/contributing/setting-up-your-local-dev-environment/)
+and that you're on the latest version of `gatsby-dev-cli`.
+
+- In the Gatsby monorepo find the starter in the `/starters` directory that uses the theme you want to work on
+- Navigate to that directory, e.g. `cd starters/gatsby-starter-blog-theme`
+- Install dependencies: `yarn`
+- Run Gatsby Dev CLI to sync theme files, referencing the appropriate theme: `gatsby-dev --packages gatsby-theme-blog`
+- In another tab run the starter: `yarn develop`
+- Edit the theme files, you'll see changes automatically copied over and update in your starter.
+
 ## Feedback
 
 At any point during the contributing process the Gatsby team would love to help! For help with a specific problem you can [open an issue on GitHub](/contributing/how-to-file-an-issue/). Or drop in to [our Discord server](https://gatsby.dev/discord) for general community discussion and support.

docs/contributing/docs-and-website-components.md → docs/contributing/docs-and-blog-components.md

@@ -1,13 +1,13 @@
 ---
-title: Docs and Website Components
+title: Docs & Blog Components
 tableOfContentsDepth: 2
 ---
 
 The Gatsbyjs.org site has a handful of components that have been developed to facilitate writing new content for the blog and the docs. There are also components that help organize and lay out content in various pages across the website.
 
-This guide documents what components are available and explains how to use them. You can also refer to the [code for this page on GitHub](https://github.com/gatsbyjs/gatsby/blob/master/docs/contributing/docs-and-website-components.md) to see to how each component can be used, because they are all embedded here!
+This guide documents what components are available and explains how to use them. You can also refer to the [code for this page on GitHub](https://github.com/gatsbyjs/gatsby/blob/master/docs/contributing/docs-and-blog-components.md) to see to how each component can be used, because they are all embedded here!
 
-Information about authoring in Markdown and styling components on the site is also listed.
+Information about authoring in Markdown on the site is also listed.
 
 ## Globally available components
 
@@ -163,7 +163,7 @@ The Horizontal Nav List component takes two props:
 - `slug` - which is provided in the props of the page by default
 - `items` - an array of strings for items to render and wrap with a `<Link />` to subheadings
 
-The docs on Gatsbyjs.org use the [gatsby-remark-autolink-headers](/packages/gatsby-remark-autolink-headers/) plugin to automatically apply hover links to heading tags across docs pages. Because it automatically creates links to subheadings on pages like the glossary, the Horizontal Nav List can supply matching links (like `"guide-list"` which would align with the automatically created link at `/docs/docs-and-website-components#guide-list`).
+The docs on Gatsbyjs.org use the [gatsby-remark-autolink-headers](/packages/gatsby-remark-autolink-headers/) plugin to automatically apply hover links to heading tags across docs pages. Because it automatically creates links to subheadings on pages like the glossary, the Horizontal Nav List can supply matching links (like `"guide-list"` which would align with the automatically created link at `/docs/docs-and-blog-components#guide-list`).
 
 <!-- prettier-ignore -->
 ```markdown
@@ -188,14 +188,14 @@ The glossary defines key vocabulary...
 Rendered, it looks like this:
 
 <HorizontalNavList
-items={[
-"guide-list",
-"egghead-embed",
-"pull-quote",
-"layer-model",
-"horizontal-navigation-list",
-]}
-slug={props.slug}
+  items={[
+    "guide-list",
+    "egghead-embed",
+    "pull-quote",
+    "layer-model",
+    "horizontal-navigation-list",
+  ]}
+  slug={props.slug}
 />
 
 ---
@@ -271,19 +271,3 @@ plugins: [
 ```
 
 Line numbers and line highlighting can be added to code blocks as well, and is explained in detail in the [`gatsby-remark-prismjs` README](/packages/gatsby-remark-prismjs/?=remark#optional-add-line-highlighting-styles).
-
-## Styling components on Gatsbyjs.org with Theme-UI
-
-Styles on the site are applied using [Theme-UI](https://theme-ui.com/), which allows for theming across the site based on design tokens (also called variables).
-
-### Design tokens
-
-Design tokens are used to consolidate the number of colors and style attributes that are applied to components throughout the site. By limiting the styles that can be applied, the site stays consistent with the guidelines for color, typography, spacing, etc.
-
-Tables listing design tokens that are used on the site can be found in the [design guidelines](/guidelines/design-tokens/).
-
-### The `sx` prop
-
-The [`sx` prop](https://theme-ui.com/sx-prop) from Theme-UI allows you to access theme values to style elements and components, it should be used wherever possible. The prop is "enabled" by adding `theme-ui`'s [JSX pragma](https://theme-ui.com/jsx-pragma) at the top of a `js` file.
-
-It is still okay to directly import tokens, e.g. `mediaQueries` or `colors` directly from [`www/src/gatsby-plugin-theme-ui`](https://github.com/gatsbyjs/gatsby/blob/master/www/src/gatsby-plugin-theme-ui/index.js) if it helps your specific use case — for example when global CSS is required, when passing theme values to other libraries or plugins, when authoring complex responsive styles, etc.

docs/contributing/docs-contributions.md

@@ -4,7 +4,7 @@ title: Docs Contributions
 
 Gatsby, unsurprisingly, uses Gatsby for its documentation website. Thank you in advance and cheers for contributing to Gatsby documentation! As of February 2019, over 800 people have contributed. It's people like you that make this community great!
 
-> _When deciding where to contribute to Gatsby (docs or [blog](/contributing/blog-and-website-contributions/)?), check out the [docs templates](/contributing/docs-templates/) page._
+> _When deciding where to contribute to Gatsby (docs or [blog](/contributing/blog-contributions/)?), check out the [docs templates](/contributing/docs-templates/) page._
 
 ## Top priorities
 
@@ -190,7 +190,7 @@ Sometimes it makes sense to move or rename a file as part of docs restructuring
 
 ```yaml:title=www/redirects.yaml
 - fromPath: /docs/source-plugin-tutorial/
-  toPath: /docs/pixabay-source-plugin-tutorial/
+  toPath: /tutorial/pixabay-source-plugin-tutorial/
 ```
 
 ## Claim your swag

docs/contributing/docs-writing-process.md

@@ -0,0 +1,96 @@
+---
+title: 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 Learning team and open source community.
+
+## Identifying a topic
+
+When identifying a topic, start by:
+
+1. Looking at GitHub issues. Good labels to seek out are [`help wanted`](https://github.com/gatsbyjs/gatsby/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+) and [`good first issue`](https://github.com/gatsbyjs/gatsby/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
+
+   - 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.
+
+2. Look at the [stub list](/contributing/stub-list/) to find docs that need contributions.
+
+3. Look at the [learning workflow meta issue](https://github.com/gatsbyjs/gatsby/issues/13708) to find active areas looking for docs.
+
+4. Read through the existing Gatsby docs information and find gaps in topic coverage. Is there an area you feel is missing? [File an issue](/contributing/how-to-file-an-issue/) to discuss it. If the team determines it warrants documentation, implement in a PR.
+
+5. 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.org`? 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**](/tutorial/) 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**](/docs/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**](/docs/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](/contributing/blog-contributions/) 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:
+
+- [Docs Templates](/contributing/docs-templates/)
+- [Gatsby Style Guide](/contributing/gatsby-style-guide/)
+
+## 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:
+
+1. As you prepare a contribution that adds documentation information, carefully read the accompanying GitHub issue for tips and relevant materials, and ask questions there.
+
+2. 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.
+
+3. 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.
+
+4. 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](/contributing/pair-programming/).
+
+5. **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](/contributing/docs-templates/) to ensure you’re producing content in the right format for its purpose.
+
+Use the [Markdown syntax doc](/docs/mdx/markdown-syntax/) to understand your options for formatting text with Markdown, and follow [accessibility recommendations](/docs/making-your-site-accessible/#how-to-improve-accessibility) for [heading levels](/contributing/docs-contributions/#headings) and image alt text.
+
+Run the docs site locally to check formatting and functionality. There are instructions in the [contributing docs](/contributing/docs-contributions/).
+
+Refer to the [Gatsby style guide](/contributing/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](/contributing/how-to-open-a-pull-request/).
+
+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.
+
+## Reference links
+
+- [Docs Contributions](/contributing/docs-contributions/)
+- [Docs Templates](/contributing/docs-templates/)
+- [How to File an Issue](/contributing/how-to-file-an-issue/)
+- [Gatsby Style Guide](/contributing/gatsby-style-guide/)
+- [Markdown Syntax Doc](/docs/mdx/markdown-syntax/)
+- [Pair Programming](/contributing/pair-programming/) for interviewing the core team only
+- [Blog Post Guidelines](/contributing/blog-contributions/)
+- [Docs site setup instructions](/contributing/docs-contributions/#docs-site-setup-instructions)
+- [How to Open a Pull Request](/contributing/how-to-open-a-pull-request/)