[contributing] update docs on guides & contributions (#20057)

* add missing steps to the docs setup instructions

* chore: contributing info for guide types

* add instructions on pushing to remote forks

* remove extra line from doc-links

* add note about other guides to Style Guide

* Apply suggestions from code review

Co-Authored-By: Aisha Blake <aisha.g.blake@gmail.com>
Co-Authored-By: LB <barth.laurie@gmail.com>

docs/contributing/docs-contributions.md

@@ -84,6 +84,7 @@ If you wrote a new document that was [previously a stub](/contributing/how-to-wr
 
 After going through the [development setup instructions](/contributing/setting-up-your-local-dev-environment/), there are a few additional things that are helpful to know when setting up the [Gatsby.js docs site](/docs/), which mostly lives in the [www](https://github.com/gatsbyjs/gatsby/tree/master/www) and [docs](https://github.com/gatsbyjs/gatsby/tree/master/docs) directories. There are also some [examples](https://github.com/gatsbyjs/gatsby/tree/master/examples) in the repo that are referenced in docs.
 
+- Prerequisites: install Node.js and Yarn. See [development setup instructions](/contributing/setting-up-your-local-dev-environment/).
 - [Fork and clone the Gatsby repo](/contributing/setting-up-your-local-dev-environment/#gatsby-repo-install-instructions).
 - For docs-only changes, consider using `git checkout -b docs/some-change` or `git checkout -b docs-some-change`, as this will short circuit the CI process and only run linting tasks.
 - Change directories into the docs site folder: `cd www`

docs/contributing/docs-templates.md

@@ -8,6 +8,7 @@ Here are some things to keep in mind when deciding where to contribute to Gatsby
 
 - [Blog posts](/contributing/docs-contributions#contributing-to-the-blog) are primarily made for case studies and time-sensitive storytelling.
 - [Reference guides](#reference-guides), in contrast, are evergreen -- or continually relevant -- and discoverable documentation articles that go beyond any one case study or situation.
+  - [Other guides](#other-types-of-guide-articles) add documentation for specific purposes like the API reference, Conceptual Guide, Gatsby Internals, and more.
 - [Recipes](#recipes) add concise, discoverable, and easy-to-follow instructions for common Gatsby tasks. They are smaller units than tutorials.
 - [Tutorials](#tutorials) should provide step-by-step guidance for Gatsby workflows, listing all pre-requisites and not assuming knowledge or skipping steps.
 
@@ -21,7 +22,19 @@ Here are templates (models) to follow when contributing to Gatsby docs to ensure
 
 Reference guide articles cover discrete topics as documentation with links to other resources. A reference guide explains a Gatsby concept or technique without the step-by-step context provided by a tutorial or recipe.
 
-Reference guide sections provide canonical information on how and why to build things with Gatsby for a variety of scenarios.
+Reference guide sections provide canonical information on how and why to build things with Gatsby for a variety of scenarios. Reference material should list text headings for each section of a guide, rather than "steps 1-5" like a tutorial.
+
+#### Other types of guide articles
+
+The Gatsby docs include multiple types of guides. They mostly follow the same format, but some docs will have a slightly different purpose and/or audience.
+
+- [Reference Guides](/docs/guides/): explanations of Gatsby site development techniques and common workflows. These should be written for all skill-levels.
+- [API Reference](/docs/api-reference/): technical docs on API methods and options, common files, and links to additional resources and explanations.
+- [Releases & Migration](/docs/releases-and-migration/): release notes and guides on how to upgrade Gatsby and third-party packages.
+- [Conceptual Guides](/docs/conceptual-guide/): high-level docs to explain important Gatsby concepts and philosophies.
+  - As an example, "Plugins, Themes, and Starters" would be an overarching concept article, with individual reference guide sections for Plugin, Theme, and Starter docs.
+- [Gatsby Internals](/docs/gatsby-internals/): previously titled Behind the Scenes, these docs go in depth into how Gatsby works under the hood.
+- [Using Gatsby Professionally](/docs/using-gatsby-professionally/): articles on winning over stakeholders, working in larger organizations, and building a career as a Gatsby developer.
 
 ### What should a reference guide be about?
 

docs/contributing/gatsby-style-guide.md

@@ -32,7 +32,7 @@ examples:
 - [Plugin README](/packages/gatsby-source-filesystem/)
 - [Starter README](https://github.com/gatsbyjs/gatsby-starter-default)
 
-Please see the [Docs templates](/contributing/docs-templates/) for guidelines on how to format the above kinds of documents.
+Please see the [Docs templates](/contributing/docs-templates/) for guidelines on how to format the above kinds of documents, as well as tips for different types of guide articles.
 
 ## Writing process
 

docs/contributing/managing-pull-requests.md

@@ -24,6 +24,8 @@ Some general things to verify in a pull request are:
 
 > 💡 When looking at a PR for the first time, it can help to read up on linked issues or [RFCs](/contributing/rfc-process/) (if there are any) to gain context on what the PR intends to add or fix.
 
+Note for Gatsby Core or Learning team members: if a PR has merge conflicts or needs a little help to push it across the finish line, contributing directly to a fork or branch can be a great way to resolve it. See notes on [pushing to a remote fork in Git](#pushing-changes-to-a-remote-fork).
+
 ### Type Specific Guidelines
 
 Each kind of PR also requires a different set of specific checks from us before they are merged in.
@@ -140,6 +142,18 @@ These are bad PR titles because they are generic, don't communicate the change p
 - Be objective and limit nitpicks (a few are fine if they add value or improve code readability)
 - Don't suggest and expect changes out of scope which are best addressed in a separate PR
 
+## Pushing changes to a remote fork
+
+Sometimes the easiest way to unblock a stalled PR is to sort out merge conflicts or apply remaining suggestions. When the GitHub UI won't cut it, you can (often) apply changes directly to someone's remote fork with Git:
+
+- Add their Gatsby fork as a remote:<br />`git remote add <forkname> git@github.com:<username>/gatsby.git`
+- Fetch the branches:<br />`git fetch <forkname>`
+- Check out their branch locally:<br />`git checkout -b <branch-name> <forkname>/<branch-name>`
+- Make your changes, add some commits
+- Push branch to the remote fork (also see [Gotchas](#gotchas) below):<br /> `git push <forkname> head:<branch-name>`
+
+Alternatively, you can manage forks and branches with [hub](https://github.com/github/hub).
+
 ## Rights and Permissions
 
 ### Who can review a PR?

docs/docs/api-reference.md

@@ -3,6 +3,6 @@ title: Gatsby API Reference
 overview: true
 ---
 
-Learn more about Gatsby APIs and configuration.
+Learn more about Gatsby API methods and options, common files, and customizations.
 
 <GuideList slug={props.slug} />

docs/docs/conceptual-guide.md

@@ -3,6 +3,6 @@ title: Conceptual Guide
 overview: true
 ---
 
-Read high-level overviews of the Gatsby approach.
+Read high-level overviews of important Gatsby concepts and philosophies.
 
 <GuideList slug={props.slug} />

docs/docs/releases-and-migration.md

@@ -3,6 +3,6 @@ title: Releases & Migration
 overview: true
 ---
 
-Find release notes and guides for migration between major versions.
+Find release notes and guides on how to upgrade Gatsby along with third-party packages.
 
 <GuideList slug={props.slug} />