Skip to content

Commit

Permalink
[contributing] add notes about docs and PR expectations (#21065)
Browse files Browse the repository at this point in the history
* add notes about docs and PR expectations

* add a bit more detail about code demos

* be extra explicit about PR approval requirements

* Apply suggestions from code review

Co-Authored-By: Aisha Blake <[email protected]>
  • Loading branch information
Marcy Sutton and Aisha Blake authored Jan 31, 2020
1 parent 03a26cb commit 65d36d8
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 4 deletions.
9 changes: 7 additions & 2 deletions docs/contributing/docs-templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ Here are some things to keep in mind when deciding where to contribute to Gatsby
- [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.

When writing (or reviewing) learning materials that show Gatsby users how to complete tasks, you are expected to **test out any code examples or steps to ensure they work**. This can also help with writing in your own words, rather than copying from other sources. If you have a demo project or code example that strengthens docs and you don't know where to put it, mention it to the Gatsby Learning team in a PR.

### Why use templates?

Here are templates (models) to follow when contributing to Gatsby docs to ensure that the docs accomplish their purpose. If you have a good reason to deviate from the following template structures, mention those reasons in the PR so others can give proper feedback.
Expand Down Expand Up @@ -198,6 +200,7 @@ A recipe should list requirements and include a few short instructions to comple

The components of a recipe are:

- Overview link on [`recipes.md`](https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/recipes.md)
- The name of the recipe, which should describe a single task
- A 1-2 sentence description motivating what the recipe is for
- Prerequisites and requirements
Expand All @@ -209,8 +212,6 @@ Recipes should be short. This is accomplished by limiting steps to what is uniqu

If you're finding a recipe is becoming too long to fit on the Docs Recipes page due to including many prerequisites or steps, consider writing a tutorial instead.

> Note: If you add a new recipe to the existing sections, be sure to add it to the list on the [`recipes.md` landing page](https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/recipes.md)!
### Recipe categories

Grouping recipes by topic will allow users to navigate and learn by subject matter. As recipes following the new format are introduced, you might find a section needs an h2 heading added for the group. The older-style recipes should be gradually replaced with actionable recipes following the template below.
Expand All @@ -235,6 +236,10 @@ Here's a template for a new recipe category:

### Recipe parts

#### Overview link

To make sure your recipe is linked from the overview page, you must add it to the appropriate category in [`recipes.md`](https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/recipes.md). Otherwise, it will be difficult for Gatsby users to find it, which isn't good for anyone!

#### Title and description

To help motivate the purpose of a recipe, its title should clearly indicate the task being covered; not just the tool or API being used. E.g. "Using the StaticQuery Component" is more descriptive than "StaticQuery".
Expand Down
7 changes: 5 additions & 2 deletions docs/contributing/managing-pull-requests.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,8 @@ We typically look for the following in [PRs that add documentation](/contributin
- Headings – whether the heading levels in a doc start with h2 (`##` in Markdown) and grow in order, establishing an accessible content hierarchy
- Type & Format – whether docs and learning materials align with our recommendations and [docs templates](/contributing/docs-templates/)

If a PR includes code examples, tutorials, recipes, or actionable guides, the reviewer must test out the material to ensure accuracy. **No PRs should be approved or merged that haven't been vetted for errors or omissions.**

#### Code

For [PRs that add code](/contributing/code-contributions/) (whether a feature or fix), we look for the following:
Expand All @@ -63,10 +65,11 @@ For PRs that add a site or a starter to the showcase, we ought to check:

For PRs that add a blog post, we ought to check:

- Approval – has the [blog post been approved](/contributing/blog-and-website-contributions/) by marketing or another Gatsby internal team?
- Correctness — whether the added documentation is technically correct
- Style — whether the written language follows our [style guide](/contributing/gatsby-style-guide/)
- Subject matter — blog posts should not be purely promotional, spammy, or inappropriate. An author should check with a member of the Gatsby team that their post is appropriate for the blog before creating their PR.
- Time Sensitivity — blog posts are more time dependent than docs, especially since they get buried after more posts are published. If something is continually relevant and more of a general how-to, it should probably go in the [Reference Guides](/docs/guides/) section of the docs.
- Time Sensitivity — blog posts are more time dependent than docs, especially since they get buried after more posts are published. If something is continually relevant and more of a general how-to, it should go in the [Reference Guides](/docs/guides/) or [Tutorials](/tutorial/) section of the docs.

## Automated Checks

Expand Down Expand Up @@ -169,7 +172,7 @@ Every PR opened in the repository needs to be approved before it can be merged.
Typically this is:

- **gatsbyjs/core** for Code
- **gatsbyjs/docs** for Documentation
- **gatsbyjs/learning** for Documentation

We also have `CODEOWNERS` set on different parts of the repo and an approval by someone in the `CODEOWNERS` for the file(s) the PR is changing can also suffice.

Expand Down

0 comments on commit 65d36d8

Please sign in to comment.