[docs] Gatsby Style Guide blitz for those new to open source

[marcysutton]

Summary

There are a ton of opportunities for small improvements to the Gatsby Docs that Hacktoberfest fans could take on. For folks new to open source, here are some ideas for contributing to the docs to make them adhere to the Gatsby Style Guide:

• Update Markdown docs titles to use Title Case
• Update titles in the docs sidebar to use Title Case
• Update pronouns in a doc to use "you" and "your" instead of "we" and "our"
• Fix the heading order of a doc to create an accessible content hierarchy (e.g. removing an extra h1, making headings go in order, etc.)

Other suggestions are welcome: chime in through the comments below! One approach could be to do a small set of changes to 5-10 docs in a PR, but one change at a time would be welcome too.

Process recommendations

To make sure your PR is accepted, try to limit its scope to changes that form logical groups. For example, a PR with 5-10 title case changes or a PR with pronoun changes from "we" to "you" would be helpful (see the Style Guide for when the subject of "we" is referring to the code).

Motivation

Grammar enthusiasm and Hacktoberfest for the win!

Additional resources

• Gatsby Hacktoberfest umbrella issue
• Gatsby Style Guide
• How to Open a PR
• Docs contributions

If you have any questions, feel free to reach out to us here on GitHub or on Twitter or Discord. https://www.gatsbyjs.org/contributing/how-to-contribute/#not-sure-how-to-start-contributing

[aditsachde]

I would like to work on this. I am going to start with the documents in the contributing folder, if others want to work on a different set of documents.

[andiegonzalez]

I would also like to contribute to this! I can start working with the Tutorials section of the documentation. Is that okay?

[marcysutton]

Sounds great, @andiegonzalez!

[ghost]

I'd love to work on this. We're looking at incorporating Gatsby at our agency and combing through the docs seems like a great way to get more familiar! Can I tackle the themes docs?

[bhautikbharadava]

Hey, @marcysutton I would like to work on this issue. Can you help me with what should I pick up?

[aitchiss]

I'd like to help with this - it looks like most people are tackling specific folders, and some odd files already have PRs, so with the hope of not treading on anyone's toes, I'd be happy to look at markdown files in the docs folder beginning with 'w' (so 'webpack-and-ssr.md' down to 'write-pages.md'

[BeniRupp]

Cool, I will have a look at all files starting with 'u' and 'v' in docs/docs/. That is unit-testing.md down to v2-release-notes.md.

[samrae7]

Taking a similar approach, I will do all files in docs starting with t

[marguerrrite]

Love this. I think "R" is up for grabs in the docs folder so I will snag those.

[KorawitRupanya]

Are there any works that I can do?

[muescha]

@KorawitRupanya

you can look for ideas at the Hacktoberfest 2019 Umbrella Issue

[marcysutton]

Is the you / your here formal or informal?
For some translations it is important.
My guess was informal but I may be wrong ...

@muescha this PR only covers changes in the English repo, and there isn't really a formal "you" other than "you", and we aren't going to use "thou".

Once #18424 is merged, there will be further instructions for translation repos.

[jasonbodman]

I'll take a look at files in the docs folder beginning with "L" if no one has taken them up.

[KiranAkadas]

I'll take a look at the files starting with 'g' if left out

[josephkmh]

I'm taking a look at files starting with "p" and "q"

[sarahzdev]

looks like 'o' and 'f' are left so i will take a look at those files

update: edited pronouns in these files -
adding-a-list-of-markdown-posts
adding-comments
adding-forms
adding-search-with-algolia
adding-search-with-js-search
adding-search
audit-with-lighthouse
bulma
centralizing-your-sites-navigation
creating-a-source-plugin
debugging-async-lifecycles
debugging-the-build-process
emotion
environment-variables
graphql-reference
migrating-from-v0-to-v1
sourcing-from-buttercms
unit-testing
using-fragments
using-gatsby-image
why-gatsby-uses-graphql

[jasonbodman]

Hi - I'll take the available "B" files in the docs/docs folder. (I think that is "babel" to "browser" since the "building" docs are already claimed.

[brkn]

I will work on the 'n' files in docs/docs.

[marcysutton]

Hacktoberfest is now over, so I'm going to close this issue. Sincere thanks to each and every one of you who took time to contribute to the Gatsby docs: we appreciate you! Stay tuned for more information about this year's custom swag -- you should be notified via email. 💜