docs reorganization

[meganesu]

Background

Refer to #27856 for more details about the documentation reorganization project.

[calcsam]

We've double-checked this pretty exhaustively.

[gillkyle]

As far as Information Architecture goes, noticed that the How to Guide and Reference section share the same sub sections:

How to	Reference

However, the conceptual guides have different subsections. I guess I see that as a little confusing, if they are the same in these 2 sections, I almost expect them to be the same across all 4 types (How to, Reference, Conceptual, etc.)?

[meganesu]

However, the conceptual guides have different subsections. I guess I see that as a little confusing, if they are the same in these 2 sections, I almost expect them to be the same across all 4 types (How to, Reference, Conceptual, etc.)?

Hmm good point @gillkyle. We were trying to help people use a consistent mental model of all the information, but maybe that's more confusing if it's not consistently consistent.

Here's another structure I was playing with at one point. Does that feel any better?

• Gatsby Project Structure (standalone doc)
• Gatsby CLI commands (standalone doc)
• Built-in React Components (dropdown)
  • Gatsby Link
  • Gatsby Image
• Config Files (dropdown)
  • gatsby-config.js
  • gatsby-node.js
  • gatsby-browser.js
  • gatsby-ssr.js
• Build Process (dropdown; NEW, needs to be written)
  • Dev build
  • Prod build
  • Lifecycle APIs? (possibly... what actually are these?)
• GraphQL Data Layer (dropdown)
  • GraphQL API
  • How to Use GraphQL Fragments
  • Customizing the GraphQL Schema
  • Node Model
  • Node Interface (possibly merge with Node Model, not sure what the difference is)
• Release Notes (dropdown)

[gillkyle]

@meganesu I think "consistently consistent" pretty well states what I'd expect! A few consistent categories would work for me if it were in every section I think.

Here's another structure I was playing with at one point. Does that feel any better?

• Gatsby Project Structure (standalone doc)

• Gatsby CLI commands (standalone doc)

• Built-in React Components (dropdown)

  • Gatsby Link
  • Gatsby Image

• Config Files (dropdown)

  • gatsby-config.js
  • gatsby-node.js
  • gatsby-browser.js
  • gatsby-ssr.js

• Build Process (dropdown; NEW, needs to be written)

  • Dev build
  • Prod build
  • Lifecycle APIs? (possibly... what actually are these?)

• GraphQL Data Layer (dropdown)

  • GraphQL API
  • How to Use GraphQL Fragments
  • Customizing the GraphQL Schema
  • Node Model
  • Node Interface (possibly merge with Node Model, not sure what the difference is)

• Release Notes (dropdown)

Would this live in just the Reference section then? Looks good to me though.

[meganesu]

Would this live in just the Reference section then?

Yep, that would be the structure for the Reference chunk of the sidebar.

I guess the underlying question is: does that new grouping of concepts make more sense than what we have now? I'm wondering what your gut feeling is, based on your experience using the docs when you're trying to look something up.

[meganesu]

Looks good to me though.

Whoops, commented before I saw this part 😅 Ok, I'll make the updates to the folder structure and the redirects!

[gillkyle]

haha that's on me, I edited my comment! @meganesu

For me (and I'm just one individual looking at this so take this with a grain of salt) I feel like I go to the the APIs for gatsby-node most, and those are given a little more prominence with the alternate architecture. I don't want to derail your thoughts on this and introduce a bunch of other work but I think that would reduce some of the confusion I first had jumping between those pages.