Pwa-studio: Discovery: Dev Docs Feedback and Gap Analysis

[awilcoxa]

Goal: Determine current gaps in developer documentation based on survey analysis as well as review of existing docs. Expected outcome is a prioritized project plan for upcoming docs/tutorials which will be logged as issues in backlog.

[jcalcaben]

Dev experience research takeaways:

• Most developers do not learn initially by reading through the docs, they often just jump in and start playing with code.
• Developers often go to docs for reference or troubleshooting information
• Some developers prefer to jump straight to the code snippet instead of reading what it does first.

Things to consider doing:

• Instead of just documenting the "happy path" for doing something, we should also highlight potential problems/failures and provide ways to recover.
• Spend more time talking to devs about how they consume docs
• Research how similar information is presented in other doc sites

[jcalcaben]

Proposed tutorials

Build a To-Do list application

This beginner-level tutorial will guide the reader through the process of creating a simple To-Do application using PWA Studio components.
It is meant to be an introductory tutorial for showing developers how to work with React and Redux in the context of simple PWA Studio components.

Things to cover

• How to create React components
• How to use Redux to hold application state
• Importing and using PWA Studio components from Venia and Peregrine
• Adding style to PWA Studio components

Setting up a simple UPWARD server

This beginner-level tutorial will guide the reader through the process of creating a simple UPWARD server.
It will start by using the sample echo configuration found in the UPWARD-spec package.

Things to cover

• How to import the UPWARD-js server
• Defining the UPWARD-spec file for the UPWARD-js server
• Showing the various ways of using the UPWARD-js library to get a server up and running
• Bonus: Find a way to build upon the previous tutorial

Build a more complex UPWARD-backed application

This intermediate-level tutorial will guide the reader through the process of creating a more complex application backed by an UPWARD server which connects to an external service, such as as REST or GraphQL.

Things to cover

• Defining a more complex UPWARD-spec that show how the server can act as a proxy for an external service
• Using a router to show different pages
• Passing GraphQL or REST data to React components

Build a PWA Storefront

This advanced-level tutorial will guide the reader through the process of creating a simple storefront using PWA Studio technologies.
This is meant to be a guide for starting a storefront project from scratch instead of relying on modifying the Venia project.

Things to cover

• Initial project setup and dependency installation
• Connecting to a Magento instance
• Using various Peregrine components to define the application
• Styling components
• Adding component interactivity

Note: This tutorial probably won't be possible until the majority of the Venia -> Peregrine conversion is complete

[jcalcaben]

Other proposed topics

Coding/Project standards

A topic that goes over the conventions for working on and with PWA Studio.

Things to cover

• Naming conventions
• Directory structure
• Docblocks

Deploying a PWA Studio storefront to production

A topic that outlines the methods for deploying a PWA Storefront into production

Things to cover

• Step-by-step deployment process
• Other best practices
• Gotchas and other pitfalls

[brendanfalkowski]

Bit of feedback. I'm 100% the opposite, so this was surprising. Don't know if I'm the weird one.

Most developers do not learn initially by reading through the docs, they often just jump in and start playing with code.

Tutorials

These sound most useful (right now):

• Coding/Project standards
• Build a To-Do list application
• Setting up a simple UPWARD server

These don't sound useful (right now):

• Build a more complex UPWARD-backed application
• Build a PWA Storefront (it would be, but see below)
• Deploying a PWA Studio storefront to production

Missing ideas I wish were here:

• Modifying Venia right now to build a PWA Storefront without cutting off upstream updates.
• API design (as a GraphQL module) for backend developers.

How Venia looks from the outside

I feel like 80% of Magento sites are squarely between "start from nothing" and "just change the colors in Venia". That's really what I'd like to see good (and bad) examples in service of.

So far (as a frontend dev) I've spent more time helping the backend team get acquainted with GraphQL and writing GQL modules for custom modules. Working on Components is frozen because it's not clear how to use Venia today aside from forking pieces in situ.

[soumya-ashok]

@brendanfalkowski Thanks for your feedback and suggestions!

Most developers we've spoken to have said that they usually go to docs to either look up commands or copy code snippets, or only to troubleshoot when they run into an issue. We have met a couple who say they do read docs with an intent to learn, but more seemed to fall in the former category. We are trying to structure the PWA docs site to address the needs of both groups to some degree.

[rossmc]

@jcalcaben I see this issue is closed, are these proposed tutorials something you're planning on providing? If so any idea as to when? I would find them very useful.

Thanks :)

[jcalcaben]

@rossmc
yes, this issue covered only the creation of a doc plan. these topics are certainly on the docs roadmap for the near future.