[docs] [workflows] Building for E-commerce

[kylefloros]

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 build an E-commerce site.

Payments are an intimidating topic. I think fleshing out the intro paragraphs to elaborate on the JAMstack approach and 3rd party payment systems right off the bat might help push newcomers towards starting the tutorial. Once they start, the tutorials are well done, and it's painless to get to the point where you're communicating with the stripe API. The verbiage that's there now isn't enough to really sway a newcomer, and a veteran just looking for the tutorial will have no problem scrolling past the longer intro.

Evaluation

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

Steps taken to implement

1. Searchability
   Google searches for...

   • "gatsby ecommerce" => 1st result E-Commerce Tutorial
   • "gatsby stripe" => 1st result Gatsby-plugin-stripe then E-Commerce Tutorial
   • "gatsby shopping cart" => 1st result E-Commerce Tutorial
   • "gatsby payments" => 1st result E-Commerce Tutorial, then gatsby-plugin-stripe-checkout
   • "gatsby store" => 1st result Swag store then Gatsby Swag Store Case Study

2. Discoverability

   • 2 Clicks: Tutorials > Making an e-commerce Gatsby Site with Stripe
   • Fairly easy to find through search on gatsbyjs.org
     • Blog results appear first when spelled w/o "-"
   • [rec] Though it overlaps with APIs, should eCommerce be called out specifically somewhere on the homepage as a use case, or in the main homepage animation? It's easily discoverable when searching for it, but not easy to stumble across for being a major use case (either showcase tags, or buried in tutorials).

3. Completeness

   • Followed "Gatsby E-Commerce Tutorial"
   • Completed Easy One Button, Advanced (Stripe Source Plug-in), and Advanced (card per SKU) walkthroughs in an hour and a half. I didn't have to do any outside Googling.

4. Linkedness

   • Tutorial is prefaced with the fact that it's an "advanced tutorial", and recommends taking the main tutorial first to speed things up. Because of that, I'm not expecting as much linkedness on the Gatsby Docs side.
   • Excellent job of linking directly to every action that needs to be taken in Stripe.

5. Tone

   • The core of the tutorials are exactly what I'd be looking for in an advanced and eCommerce-specific tutorial.
   • [rec] The "Why use Gatsby for an e-commerce site?" and "How does Gatsby work with Stripe?" could be rewritten and targeted toward giving people who are not familiar with JAMstack or using third party payment systems that little extra boost to stick it out and go through the tutorial. Payments are intimidating. Maybe mentioning an "estimated time to complete this tutorial" could help as well. It really is painless once you get started.

6. Style

   • Effective but could use a little polish
   • Nice progression through the one-button and advanced tutorials
   • [rec]
     • Create a small table of contents for the easy and advanced tutorial once you hit those sections, or pull Examples back out to the h1 level.
     • Link to the Advanced page of the demo app in the Advanced section of the tutorial. It's easy to miss the small link to the advanced page at the bottom of the demo app when you first click on the demo app in the introduction because the "BUY MY BOOK" button dominates.
     • The tutorial ends somewhat abruptly. Maybe a wrapping up section, FAQ/Challenges, or links to Stripe alternatives would be nice.

7. Overall

   • I think you have this workflow largely covered. Searchability, discovery, and the tutorials are excellent.

Recommendations

1. Though it overlaps with APIs, should eCommerce be called out specifically somewhere on the homepage as a use case, or in the main homepage animation? It's easily discoverable when searching for it, but not easy to stumble across for being a major use case (either showcase tags, or buried in tutorials).
2. Create a small table of contents for the easy and advanced tutorial once you hit those sections, or pull Examples back out to the h1 level.
3. Link to the Advanced page of the demo app in the Advanced section of the tutorial. It's easy to miss the small link to the advanced page at the bottom of the demo app when you first click on the demo app in the introduction because the "BUY MY BOOK" button dominates.
4. The tutorial ends somewhat abruptly. Maybe a wrapping up section, FAQ/Challenges, or links to Stripe alternatives would be nice.
5. The "Why use Gatsby for an e-commerce site?" and "How does Gatsby work with Stripe?" could be rewritten and targeted toward giving people who are not familiar with JAMstack or using third party payment systems that little extra boost to stick it out and go through the tutorial. Payments are intimidating. Maybe mentioning an "estimated time to complete this tutorial" could help as well. It really is painless once you get started.

[AishaBlake]

This is mostly a reminder to myself to go through issue #2586 and make sure the kind of information shared there is accurate and discoverable in the docs. Seems like there was a particularly fruitful conversation even after the issue was closed and I want to verify that it was/is captured.

[laurieontech]

@AishaBlake given all the work recently done on this topic, is this larger issue still necessary? Or should we close it in favor of smaller scoped issues?

[AishaBlake]

We've made significant strides on the e-commerce workflow and I think this larger issue can be closed now that the Snipcart documentation is merged! 🎉