[docs][workflows] using GraphQL in Gatsby

[marcysutton]

Part of the Top 25 Learning Workflows initiative. See #13708 for the meta issue that this issue falls under.

User story

As a new Gatsby user, I want to understand how GraphQL works in Gatsby and get it working properly in a project.

The motivation for this issue is to make sure users aren't deterred from using Gatsby by what they find when searching the docs for GraphQL information. There's a ton of it on there already, including why Gatsby uses GraphQL and how to build sites without it. However, some of the docs don't have the most intuitive titles or locations for people to find information easily (like API docs). We have added recipes recently, which helps! But given the importance of GraphQL in Gatsby, we should take a deeper look at it similar to what we did with images.

Evaluation

Search	Discover	Complete	Linked	Tone	Style	Overall
😄	😐	😄	😐	😐	😐	😄

Steps taken to implement

1. Searchability:

   • Searched graphql in gatsby: first result Querying with GraphQL (name of that article is a little confusing when this a conceptual guide, maybe should include a note distinguishing this from the reference guide on GraphQL, also renaming this to show that's conceptual would be helpful and would solve the naming collision between this and the reference guide page)
   • Search gatsby graphql same first and second result as the first search (Querying data with GraphQL and then GraphQL and Gatsby)

2. Discoverability:

   • Searched graphql in the .org search bar which shows a blog post for Kentico Cloud as the first result and "Gatsby without GraphQL" as the second 😱(which seems to be a result of this section being in the sourcing data section before GraphQL is introduced, maybe move Using Gatsby Without GraphQL in the sidebar to below Sourcing from (Headless) CMSs), the 3rd result is "GraphQL and Gatsby"

3. Completeness:

   • Good level of content addressing lots of use cases, the recipes give some quick, digestable examples and there are several reference guides, mostly on querying and creating pages
   • Followed steps in Creating and Modifying Pages as it appeared to be the most relevant by title to actually writing code
     • really thorough, realized the same content can be found in multiple places across the docs

4. Linkedness

   • There are definitely many links to other locations in the docs but it can get confusing quickly because the pages aren't named super well. Some of the already recorded recommendations would help because a doc will sometimes link to Querying with GraphQL in the conceptual guides when a link to the reference guide docs would help give more step by step info (good example conceptual guide is what's expected clicking that link / poorer example while trying to set things up a conceptual guide doesn't make as much sense, but the title and link text doesn't tell you it's only conceptual)

5. Tone

   • informative for API related docs, friendly in guides and especially tutorial

6. Style

   • 👍

Recommendations

• The GraphQL reference page isn't discoverable - the h1 and sidebar titles are different (maybe rename GraphQL Query Options Reference) (docs: graphql api page and other incremental improvements #17516)
• make source types searchable with a clear API reference (e.g. allFile, GatsbyImageSharpFluid, similar to the Gatsby Image API)
• make built-in fragments searchable with a clear API reference (e.g. allFile, GatsbyImageSharpFluid, similar to the Gatsby Image API)
• generate a list of all available types (define types that come from common plugins?)
• move Using Gatsby Without GraphQL to bottom of sourcing content and data section
• update the link on fragments in Querying Data with GraphQL > Advanced > Fragments from the GraphQL docs to Gatsby's docs that discuss fragments
• include a note at the top of the Querying Data with GraphQL conceptual guide noting the difference between it and the reference guide
• rename Querying Data with GraphQL conceptual guide to something like GraphQL Concepts (it shouldn't have that title that is also the title used for the reference guide section which when you click on says GraphQL and Gatsby)
• include a pared down version of the Query Options Reference page on the API doc with simple examples for concepts like filter/sort/limit and what parameters they take
• finish up this issue on static vs normal queries ([docs] Finish Static vs Normal Queries page #15157)

Related issues

• [docs][guides] better document Gatsby GraphQL APIs #15231

[gatsbot]

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! 💪💜

[marcysutton]

The remaining work is covered by open issues:

• [docs][guides] better document Gatsby GraphQL APIs #15231 (digestible API docs)
• [docs] Finish Static vs Normal Queries page #15157 (Finish the Static vs. Normal Queries Page)

I'm going to close this workflow issue as a result, and we can continue on those outstanding issues separately.