Gatsby: .org redesign: homepage [design] gatsby diagram

[amberleyromo]

_(This issue is design-focused, not implementation-focused.)_

@fk has begun working on and mocking up updated designs for the Gatsby homepage diagram:

This issue is intended to support discussion and feedback on the diagram update.

[fk]

I finally picked up work on this yesterday and here's what I've got so far:

FYI: With us internally deciding to expand the existing diagram and add some more detail inspired by the react-static diagram used in their "Introduction" article, I decided the vertical format is the only route to pick. Thus I completely abandoned all (long-standing) ambitions to do a vertical _and_ a horizontal (for bigger screens) version of the diagram for now.

[fk]

As you can see, I'm a little stuck on both "Build" and "Serve" parts though:

• I want to make sure that Gatsby's "build" and "serve" stages really match the ones of our reference diagram: Do "React/Gatsby Bootstrap", "Template", "JSON" really make 100% sense for Gatsby, too? /cc @kylemathews @pieh
• I'm a little confused about "JSON" being part of "Page" in react-statics "Build" step. I would have expected "JSON" to be _associated_ with "Page", but not being _part_ of it here.

I also would like to avoid copying the react-static diagram 1:1 in terms of "Build" and "Serve", but I'm missing some "Gatsby internals" knowledge to think about ways to do so. Plis halp! 🆘

• Do we want to feature @reach/router in "Serve" as react-static does with React Router?

[fk]

Further wondering:

• Should we add a "Develop" section, too? My vote is for "yes", because it allows us to point out the great dev UX features Gatsby offers (hot reloading being the main one). That's something where the react-static diagram falls short on IMO.

• I added a bunch of "explanatory copy" for "Source Data" and "Deploy" — does that make sense to y'all? The current copy is borrowed from the existing "six cards above diagram" on the current https://www.gatsbyjs.org/.

  • I initially did so because there was space, and I wanted to see how adding a short explanation would feel. ;-)
  • When adding the copy that is there now in that WIP design, I wondered if we should drastically reduce their copy, and turn them into something more "unordered list of features" kind of thing — something that can be scanned quickly to get a feature overview — while at the same time adding that copy to the diagram.

[KyleAMathews]

I'm a little confused about "JSON" being part of "Page" in react-statics "Build" step. I would have expected "JSON" to be associated with "Page", but not being part of it here.

Yeah — theirs and our build steps generate JSON (the data for each page)

Do we want to feature @reach/router in "Serve" as react-static does with React Router?

I'd vote yes — a lot of people aren't sure exactly how Gatsby works so emphasizing we ship a client router will help them get that "oh, Gatsby _is_ generating a React app and I can add client routes, etc."

I added a bunch of "explanatory copy" for "Source Data" and "Deploy" — does that make sense to y'all?

👍

Should we add a "Develop" section, too?

Seems promising — if it makes the diagram more confusing I'd vote for just showing the "build" diagram

I want to make sure that Gatsby's "build" and "serve" stages really match the ones of our reference diagram: Do "React/Gatsby Bootstrap", "Template", "JSON" really make 100% sense for Gatsby, too?

Yup! Except we call them "page template components" https://www.gatsbyjs.org/docs/building-with-components/ (or maybe just "page templates"

[jlengstorf]

I had an idea and put together a super rough sketch:

The general idea is that Gatsby has 3 distinct phases:

1. Sourcing (the content mesh)
2. Developing (incredible DX)
3. Building (performance, UX)

This is an attempt to show all three phases inside a “band” of Gatsby work, so we can see:

1. The data coming in from The Cloud™
2. Gatsby’s source, develop, and build steps
3. The deployment process and how that affects the UX and perf.

I could also make an argument that the “what happens when you request a Gatsby site” section is its own diagram in a separate area. These are actually two distinct concepts:

1. What does Gatsby do?
2. How are Gatsby sites so fast?

[marisamorby]

@fk @lindaleebumblebee
Based on our conversation in the .org redesign meeting today, we're going to first get requirements from marketing, sales, and product teams to get a better understanding of what we want the diagram to tell us. From there, the diagram can be redesigned.

This diagram can then be used for marketing and sales efforts, as well as on the homepage.

Next steps

• I'll get a list of requirements and post them in this issue
• We can get on a short call to discuss the requirements
• Start design work

[marisamorby]

What is the goal for the diagram?

Educate the target audience about what Gatsby IS and DOES (how it works). It should be simple enough that it can easily and quickly convey Gatsby to all developers. @amberleyromo and I discussed having an actual animation to help depict this.

What do we want people do to with it?

Come away with an understanding of how Gatsby can help them in their projects.

Who is the audience for the diagram?

Developers

What do we want the diagram to show?

• Illustration of how GraphQL works within Gatsby

Not sure if we want to link this to .com Diagram Issue (in ichabod-cranes repo Issue # 1332)

[jlengstorf]

I needed to create a way to show the Gatsby flow in slides for the GraphQL Summit, and this is what I ended up with: https://jlengstorf.github.io/presentations/beyond-static/#/20

Note that you'll need to advance through the slides to see the full diagram.

If this is helpful, I can share the Figma file as well.

[jlengstorf]

Here's the Figma link of my diagram: https://www.figma.com/file/egCho5h1PYnLcC4DppKPJiP1/Diagram-Ideas?node-id=1%3A2

[marisamorby]

This is blocked by the .org homepage research. We'll revisit once research is complete and we can get to design.

[gatsbot[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!

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

[gatsbot[bot]]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.

Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.

Thanks again for being part of the Gatsby community!