Gatsby: [doc] : Improve doc on GraphQL to offer explanation on concepts

[Ekwuno]

Summary

This issue is filed from a tweet by Laurie Voss on improvements to be made to existing GraphQL docs. We need to answer questions like

• What is a node again? Is that a gatsby thing or a graphql thing? How do I create one?

• Where do I... put the data? There's an id, a parent, children, a complicated "internal" thing... where do I put the title, body, etc. of my blog posts, which are the thing I'm trying to put in there? If I just add a key called "blogPost" it fails validation.

• "what is a gatsby node" takes me to the Node interface doc, which is just a slightly nicer explanation of the API, but still doesn't explain how I add arbitrary fields to a node or really what nodes are or what they're for.

related links

• https://www.gatsbyjs.org/docs/data-fetching/
• https://www.gatsbyjs.org/docs/node-interface/

Some recommended topics to cover:

Some solutions to this :

• you can add arbitrary fields at the top level (which seems very strange to me since there are reserved fields there too)
• you have to give them a type in the "internal" field but it can be anything, you don't have to define the type
• List the topics you think should be here.
• This list does not need to be exhaustive!

Motivation

We should address this issue because it would offer a better learning experience for Plugin authoring and working with GraphQL in a Gatsby context

Steps to resolve this issue

Changes to be made

• [ ] Add a line saying node fields can be arbitrary
• [ ] Add a comment in code example saying url and nameFromOwner are arbitrary fields from the data

Draft the doc

• [ ] Write the doc, following the format listed in these resources:
  
  
  
  • Overview on contributing to documentation
  
  
  • Docs Templates
  
  
  • Example of a similar article
  
  
• [ ] Add the article to the docs sidebar under the [parent doc] section.

[ElijahCano33]

Hi, I am a new contributor and this particular issue interests me a lot. May I begin opening up a pull request to address this ticket?

[Ekwuno]

Hi @ElijahCano33 , Thanks for showing interest in working on this. Sure you can open a PR and specify that it is aimed at closing this issue and I will happily review. 💜

[ElijahCano33]

Awesome, will do!

[github-actions[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[Ekwuno]

Hey @ElijahCano33, how's it going? Do you have any feedback on the status of the PR to close this issue?

[ElijahCano33]

Hey Ekwuno, it's going good as of right now. I was having a few hiccups with setting up the docs locally on my machine since I am on Windows. I had to submit a bug report; however, it got resolved and I was finally able to run the Gatsby docs locally. With the docs setup, I am going to try and resolve this very soon so that we can close this issue.

[ElijahCano33]

I submitted my changes to this PR.

[gillkyle]

This was addressed in #23106