PR feedback, updates from reviews

docs/contributing/gatsby-docs-translation-guide.md

@@ -8,13 +8,21 @@ If you're a native speaker of a language other than English and you're intereste
 
 ## The general process
 
-Each translation has its own repository in the [gatsbyjs](https://github.com/gatsbyjs/) organization on GitHub, with designated codeowners to review and approve changes. This doc will outline how to request a new language repository with its own team, what decisions each team can make, and suggestions for how you can work together.
+Each translation has its own repository in the [gatsbyjs](https://github.com/gatsbyjs/) organization on GitHub, with designated codeowners to review and approve changes. Each repo will include all pages needing translations (with some prioritized over others), and a bot to notify of changes in the main repo to keep everything up to date.
 
-The Gatsby learning team is in charge of determining priorities for which docs should be translated. Refer to the [i18n page spreadsheet](https://docs.google.com/spreadsheets/d/1u2amGnqFLKxJuL5h9UrDblUueFgg0EBt7xbau4n8iTM/edit) to get the most up-to-date priority list.
+This doc will outline how to request a new language repository with its own team, what decisions each team can make, and suggestions for how you can work together.
 
-## Use English as the source
+### Page translation priorities
 
-The [gatsbyjs.org](https://gatsbyjs.org) website is written in English and should be considered the source material for all translations (as opposed to translating from another translation). When a repository is created, it will provide the space to copy over prioritized docs and [make pull requests](/contributing/how-to-open-a-pull-request/) against them in the relevant language.
+The Gatsby learning team is in charge of determining priorities for which docs should be translated. Refer to the [i18n page spreadsheet](https://docs.google.com/spreadsheets/d/1u2amGnqFLKxJuL5h9UrDblUueFgg0EBt7xbau4n8iTM/edit) to get the most up-to-date priority list, which includes frequently-visited pages in the Gatsby docs, tutorial, recipes, other important pages.
+
+[Reference guide overview pages](/contributing/docs-templates/#reference-guide-overview) are also worth translating to establish a fully translated path to a frequently visited [reference guide](/contributing/docs-templates/#reference-guides), though they are listed at a lower priority. Pages not translated will appear in English alongside translated pages to present a complete website without gaps, similar to the [React.js docs](https://reactjs.org).
+
+### Use English as the source
+
+The [gatsbyjs.org](https://gatsbyjs.org) website is written first in English and should be considered the source material for all translations (as opposed to starting from another translation). When a repository is created, it will provide a copy of the docs to be translated which you can then update through [pull requests](/contributing/how-to-open-a-pull-request/) against them in the relevant language. A bot will 
+
+Changes to the meaning of a text or code example should be done in the main [English repo](https://github.com/gatsbyjs/gatsby/), and then translated afterwards to keep the content aligned across languages.
 
 ## Process for starting a new translation
 
@@ -49,23 +57,56 @@ As repo maintainers and members of the Gatsby community, your responsibilities a
 
 - Keep issues up to date as people volunteer to translate pages.
 - Review pull requests made by contributors promptly.
-- Review pull requests generated by gatsbybot in order to make sure translations remain up to date with the source repo.
+- Review pull requests generated by gatsbybot in order to make sure translations remain up to date with the source repo. (details to come)
 - Act as point of contact for your language and answer questions from both contributors to your language and the core Gatsby team.
 - Set up a process in order to get your translation published. (details to come)
 
+As a maintainer, you are welcome to add a contributing doc written in your language to assist with the process. You can find an example in the [gatsby-es repo](https://github.com/gatsbyjs/gatsby-es/blob/master/CONTRIBUTING.MD). Translating [this page](https://github.com/gatsbyjs/gatsby/blob/master/docs/contributing/gatsby-docs-translation-guide.md) and copying it into a `contributing.md` file would be an option as well.
+
 Additional tips:
 
 - Make a glossary and translation style guide. Here are some [examples from the React translation project](https://github.com/reactjs/reactjs.org-translation/blob/master/maintainer-guide.md#make-a-glossary-and-style-guide).
 - Collaborate on large or challenging pages. More than one person can contribute to a long tutorial or reference guide!
 - Set up a review process
 - Ask for help
 
+#### When a maintainer or contributor will be removed
+
+Consistent with the [Code of Conduct](/docs/code-of-conduct/) the Gatsby team reserves the right to remove a maintainer (or contributor) from the Gatsby organization if necessary. Some reasons for being removed include spammy comments, closing PRs or issues without action or productive dialogue,or generally harmful or abusive behavior inconsistent with Gatsby's policies.
+
 ### Templates for responses on PRs
 
-Sometimes a PR has a valid reason to not be merged as-is. Templates can help speed up the process of responding to someone while encouraging future contributions. Examples include:
+Sometimes a PR has a valid reason to not be merged as-is. Templates can help speed up the process of responding to someone while encouraging future contributions.
+
+#### PRs with quality issues
+
+If a PR includes content that is of poor quality (such as from Google Translate or missing important nuance) or doesn't meet the requirements, it would help to include a drafted reply to encourage contributors to continue with the project. Here is an example that can be translated for a given repo:
+
+```
+Hey! Thanks so much for opening a pull request!
+
+We really appreciate you sending this over, but the change you’ve proposed is not going to be accepted because it doesn't meaningfully translate the Gatsby docs content.
+
+We absolutely want to have you as a contributor, so please take a look at [our open issues][open-issues] for ideas and reach out to the Gatsby team [on Twitter at @gatsbyjs](https://twitter.com/gatsbyjs) with questions.
+ 
+Thanks again, and we look forward to seeing more PRs from you in the future! 💪💜
+[open-issues]: YOUR_REPO_ISSUE_URL_HERE
+```
+
+#### PRs with content changes more fitting for the main repo
+
+Because the main Gatsby repo is the source of content, more substantive changes should be closed and redirected there. Here is a template that could be translated for your repo:
+
+```
+Hey! Thanks so much for opening a pull request!
+
+We really appreciate you sending this over, but the change you’ve proposed is not going to be accepted because it includes broad changes to the docs content that should be done in the [main Gatsby repo](https://github.com/gatsbyjs/gatsby) instead.
 
-- PRs that don't meet expectations and need some work
-- ?
+We absolutely want to have you as a contributor, so please take a look at the original source for these changes and make them there first before translating. You can also visit [our open issues][open-issues] for ideas and reach out to the Gatsby team [on Twitter at @gatsbyjs](https://twitter.com/gatsbyjs) with questions.
+ 
+Thanks again, and we look forward to seeing more PRs from you in the future! 💪💜
+[open-issues]: YOUR_REPO_ISSUE_URL_HERE
+```
 
 ## Which decisions are flexible? Which are firm guidelines?
 

docs/contributing/gatsby-style-guide.md

@@ -82,15 +82,19 @@ Also, there's a community of contributors to support you. Bounce ideas off of th
 
 ### Use "you" as the pronoun
 
-In English, your articles should use the second person ("you") to provide a conversational tone. This way, the text and instructions seem to speak directly to the person reading it. Try to avoid using the first person ("I", "we", "let's", and "us"). For other languages, refer to each translation's guidelines (if applicable) for consistent phrasing.
+In English, your articles should use the second person ("you") to provide a conversational tone. This way, the text and instructions seem to speak directly to the person reading it. Try to avoid using the first person ("I", "we", "let's", and "us").
+
+For other languages, refer to each translation's guidelines (if applicable) for consistent phrasing. When appropriate, we suggest starting with the informal "you" to keep a conversational tone.
 
 Using "you" in English is also more accurate than saying "we," because typically only one person is reading the tutorial or guide at a time and the person who wrote the tutorial is not actually going through it with them, so "we" would be inaccurate. You might notice that some technical documentation uses third person pronouns and nouns like "they" and "the user," which add more distance and feel colder than the conversational and warm "you" and "your."
 
 When updating a doc to adhere to this part of the Gatsby Style Guide, one exception in English is when "we" refers to Gatsby's core processes. The subject is the code in this case, rather than a teacher/reader connotation, and should be rewritten or restructured to not confuse the reader about what they are responsible for doing when something is happening automatically behind the scenes.
 
 ### Avoid "easy" and "simple"
 
-Avoid using words like "easy", "simple," and "basic" because if users have a hard time completing the task that is supposedly "easy," they will question their abilities. Consider using more specific descriptors; for example, when you say the phrase "deployment is easy," what do you really mean? Is it easy because it takes fewer steps than another option? If so, just use the most specific descriptor possible, which in that case would be "this deployment method involves fewer steps than other options."
+Avoid using words like "easy", "simple" and "basic" because if users have a hard time completing the task that is supposedly "easy," they will question their abilities. Consider using more specific descriptors; for example, when you say the phrase "deployment is easy," what do you really mean? Is it easy because it takes fewer steps than another option? If so, use the most specific descriptor possible, which in that case would be "this deployment method involves fewer steps than other options."
+
+For even more inclusive docs, avoid phrases that assume a reader's experience or skill level, like "just deploy it and you're done" or "for a refresher (referring to a completely different doc that someone may not have read)". Often, rephrasing results in stronger sentences that appeal to a wider range of contexts.
 
 ### Avoid emojis, slang, and metaphors