Update schema and types docs

[mandiwise]

Description

This PR contains updated content for the Schema and Types page in the Learn docs. Key changes include:

• An updated intro and a new "next steps" section at the end of the page
• A new section on type system directives
• A new section on documentation (descriptions and comments)
• Updated/expanded content and examples for all existing sections
• Standardization of capitalization and naming for named types

Note that the intention is to swap the order of this page in the left nav so that it comes before the Queries and Mutations content, but this will be addressed in the next PR that updates that operation-related content.

@benjie @jorydotcom

[vercel]

@mandiwise is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[benjie]

If possible, please rebase these changes onto #1794

[benjie]

I wonder if we should be linking to the draft spec rather than a specific release. Everything in the draft has passed the RFC process and barring some exceptional circumstances will make it into the next official release - it's the version that implementations should be following/implementing, and the links are more evergreen (linking to section titles should be fine, but linking to specific words within a paragraph is probably riskier!).

[mandiwise]

If possible, please rebase these changes onto #1794

@benjie The commits from jonathanberger/patch-1 have been merged into this branch now with the conflicts resolved.

[mandiwise]

I wonder if we should be linking to the draft spec rather than a specific release. Everything in the draft has passed the RFC process and barring some exceptional circumstances will make it into the next official release - it's the version that implementations should be following/implementing, and the links are more evergreen (linking to section titles should be fine, but linking to specific words within a paragraph is probably riskier!).

@benjie I'm happy to swap out the URLs to use the draft spec path so they're more stable over time. The other option I can think of would be to create something like a <SpecLink section="some-section-id"> component to use throughout the MDX files so that when a new release of the spec is finalized the URL will only need to be updated in the component file. Let me know what you think.

[benjie]

The MDX component is an interesting approach! I think we should just link to the draft - our general advice to everyone is to follow the draft, and the draft is where any typo fixes and other such things will go so it's generally more correct/up-to-date.

[mandiwise]

Spec links have now been changed to the draft path.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
graphql-github-io	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 7, 2024 6:26pm

[benjie]

This is excellent! I've included some suggested edits, but I think this is a great improvement over the existing text - excellent work 🙌

[benjie]

Looking good just the bulleted list of schema build methods and maybe the linking of the defined terms left to consider I think!

[mandiwise]

Looking good just the bulleted list of schema build methods and maybe the linking of the defined terms left to consider I think!

These changes have been committed now.

[benjie]

Awesome; this is great! 🙌