Gatsby: [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!

[jacob-shu]

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

[margueriteroth]

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

[chadwyck242]

Just did one in the 'a' section, about adding comments functionality. Maybe I will also continue working in that area, is anybody else wanting to take some of those? Happy Hacktoberfest =)

[aditsachde]

I've gone through the contributions folder and everything seems mostly alright. If its ok, I'm also going to have a look at the docs in the 'docs/docs/' folder starting with building, around half of the 'b' articles.

[LuisPinedaJR]

Id like to help with this, I see 'q' hasn't been mentioned so I'll do that section :)

[FissionCat]

I'd like to help too! Currently looking at 'starters' through to 'styling' in the docs folder.

[SarahLKatz]

I'll take the files in the 'docs/docs' folder that start with C, if nobody else has started on those (if someone has, let me know and I'll take a different letter). It will probably be a few PRs since there are ~20 files, so I'm happy to split if anyone else is attached to the letter C.

[KiranAkadas]

I'll take the files starting with 'how', hoping no one has started working on it..

[dosden]

I would love to work on this can I take docs/docs/ files starting with A

[dosden]

18488

[KillMonger1]

I will take up files starting with 'h'. Let me know if anyone is working on it too

[kaylasween]

I didn't see anyone mention it, so I'll start on w!

[adibfirman]

sorry? is already taken by @aitchiss isn't it?

https://github.com/gatsbyjs/gatsby/issues/18284#issuecomment-539476354

I didn't see anyone mention it, so I'll start on w!

[kaylasween]

sorry? is already taken by @aitchiss isn't it?

#18284 (comment)

I didn't see anyone mention it, so I'll start on w!

Good catch! I've finished it, but won't open a pull request in case @aitchiss is still working on it. I'll move onto d. Please let me know if I missed anyone claiming that one. I don't want to step on anyone's toes!

[aitchiss]

Hey @kaylasween my changes were merged in #18331. So if your branch is up to date any you found some issues I've missed, you're good to go 🙂

[Danondso]

I'd like to help out, @marcysutton has anyone taken docs that start with m?

[codingCookie]

I'd like to contribute as well and will grab the docs/mdx folder. Is it ok?
I didn't see anyone mention it.

[codingCookie]

I'd like to contribute more 🤗 i would also grab the GraphQL-Files in docsFolder - if nobody already claimed those.

[codingCookie]

aaand another one - i will grab the letter 'i' in the docs-folder - hope nobody else already grabed it

[codingCookie]

so nobody mentioned 'p' - as far as i see - so i will take care of the p-files

[chrismgonzalez]

Looking forward to tackling some of this later tonight!

After review, looks like the 'e' section is not taken. I will work on them.

[mickm77]

Unless i missed it - 'c' looks un-taken - i'll do them...

[muescha]

@marcysutton

Update pronouns in a doc to use "you" and "your" instead of "we" and "our"

Is the you / your here formal or informal?

For some translations it is important.

My guess was informal but I may be wrong ...

[steph-chan]

I'd like to work on the remainder of the 's' docs that have yet to be worked on

[mendaomn]

I'm taking on the 'u' docs!

[aitchiss]

@mendaomn I think @BeniRupp took those a while back?

[mendaomn]

@mendaomn I think @BeniRupp took those a while back?

You are right! I totally missed his comment! I did find some punctuation fixes with the aid of Grammarly, so I was thinking to open a PR anyway. What do you think? Should I discard my changes and work on something else?

[aitchiss]

@mendaomn I'm not sure if @BeniRupp's changes are merged back yet or not, but if they are and you've spotted something else that can be tweaked, sure go for it!

[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 https://github.com/gatsbyjs/gatsby/pull/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"

[sazhang]

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. 💜