[docs][workflows] building apps with Gatsby

[gillkyle]

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 to build apps using Gatsby.

Evaluation

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

Steps taken to implement

1. Searchability:
   • Searched building apps gatsby: first result was the Building Apps with Gatsby doc that is not listed in the sidebar. Second result the blog post from Dustin about Gatsby for Apps
   • Searched dynamic data gatsby: first result was the Client Data Fetching doc

Gatsby docs are surfaced first in search results and seem to be identifiable by common search terms associated with apps (even though the exact terminology can vary).

2. Discoverability:

   • Building Apps with Gatsby doc isn't in the sidebar (like mentioned above), but finding docs like "Adding Authentication" only takes 3 clicks from the docs
   • docs on building apps, auth, and dynamic content can be found okay from the .org site search

3. Completeness:

   • client only routes and authentication pages continue to have complaints about not being easy to understand, there could be much more illustrative examples for it with real use cases
   • authentication guide links off to the client only route page as well as the authentication tutorial (but with an erroneous subheader in the link) as it's only 2 bullet points for "Setting the authentication workflow", more content here would be beneficial
   • client data fetching offers good examples and demonstrates how to perform the task well 👍 however, I think the value of this guide might more accurately be stated as "Fetching Data" since it explains both build time and client side data fetching, which might help more people land on this guide

A general trend in these guides seems to be linking off to example repos and places where these patterns are used rather than actually teaching them inline with the docs and code examples

4. Linkedness

   • Seems well interlinked 👍

5. Tone

   • The tone feels positive, it's often really terse, explanations could be a bit wordier

6. Style

   • Conforms with the style guide 👍

Recommendations

• add the Building Apps with Gatsby page to the sidebar or combine it to the existing pages in Adding Website Functionality which should maybe be renamed Adding App and Website Functionality docs: adding rehydration doc and updates to building apps overview (gatsby for apps workflow) #19214
• transfer content from blog posts on Apps with Gatsby into their respective docs:
  • "Gatsby for Apps" has content for client routing, adding authentication, and includes info about PWA's [docs] improvements to offline, PWA, and service worker guides  #20050
  • "Beyond Static: Building Dynamic Apps with Gatsby has content for overview on building apps with Gatsby, and hydration. docs: adding rehydration doc and updates to building apps overview (gatsby for apps workflow) #19214
• add more substantial examples to client only routes documentation to show the difference between adding pages through Gatsby (src/pages, createPage, and with a router like Reach) docs: gatsby for apps - auth and client only routes #19551
• increase the content on the "Building a Site with Authentication" page docs: gatsby for apps - auth and client only routes #19551
• remove stubs for "Linking and Prefetching in Gatsby" and "Rendering Sidebar Navigation Dynamically" in the routing section Rename Routing Doc and remove duplicate stub #19918
• rename Client Data Fetching -> Build and Client Time Data Fetching docs: gatsby for apps - data fetching #19786
• make a new guide (or perhaps a recipe) about Client Side Data Fetching docs: gatsby for apps - data fetching #19786
• add information about pulling in app data super quick with service workers so you don't have to wait on the network (this can also include an example of an app with a logged in user using a service worker) [docs] improvements to offline, PWA, and service worker guides  #20050
• setup a live example for examples/simple-auth docs: gatsby for apps - auth and client only routes #19551

I'll likely break these recommendations into a few contextual sections (and probably in this order):

• Overview for Building Apps with Gatsby docs: adding rehydration doc and updates to building apps overview (gatsby for apps workflow) #19214
• Authentication & Client-only routes docs: gatsby for apps - auth and client only routes #19551
• Routing Update Routing docs main page #19700 & Rename Routing Doc and remove duplicate stub #19918
• Dynamic data docs: gatsby for apps - data fetching #19786
• PWA/Service Worker/App Shell [docs] improvements to offline, PWA, and service worker guides  #20050 (tracked by the issue so marking as done)

[ghost]

I can "add the Building Apps with Gatsby page to the sidebar" by just doing a PR as well as a few of the others as well if want🤷‍♀️☺️

[gillkyle]

Thanks for offering the help @bvlktech! I think with these recommendations it'd make sense to keep most of them in one PR so that the changes can be seen side by side in the context with where docs are moving and how pages are being renamed. Since it could impact the general information architecture and I'm guessing some of the pages will be able to be combined/moved.

I'll hopefully be able to get a PR up soon that maybe you'd like to look over and review?

[ghost]

Sure thing cant wait to check it out☺️

[ghost]

did u make the PR yet? jw is all

[gillkyle]

@bvlktech I just made a first PR at #19214. I've been doing a lot of ideation around this the last few days because it's a confusing topic for a lot of people. That first PR should cover some of the groundwork around the overview and conceptualizing making app features possible -- with a doc on hydration as well.

[ghost]

yes i saw will check it out for further review thanks for getting back!

[marcysutton]

We can close this issue now, as the work has mostly been completed! The outstanding issue in #20050 can be tackled separately. Great work @gillkyle!