Interactive Tutorials

[AlecAivazis]

The GraphQL Foundation is running a Call for Projects. For my submission, I proposed building an interactive tutorial (simliar to https://learn.svelte.dev/) for users just getting started with GraphQL. The goal is to provide users with an environment to learn GraphQL from first principals, teaching best practices along the way while avoiding as many framework-specifics as possible. Clearly there will be to be some client specifics so that we have practical examples for critical features like fragments and so with that in mind I think its worth explicitly stating a few things:

• My submission would use Houdini to showcase queries and fragments but the infrastructure and layouts would be totally client-agnostic. The goal would is for this same code to power any interactive tutorial that leverages tools written with a wasm-compatible toolchain.
• The runtime would leverage WebContainers, the same technology that StackBlitz uses
• For non-Houdini tutorials there will need to be some kind of external API that we can access. This could run inside of the container so that we don't create a dependency on externally hosted services (keeping costs low). Here are the docs for running processes inside of a WebContainer.
• Ideally the components and layout would be totally portable if any tools wanted to provide similar tutorials on their own sites
• We could also build progressively more advanced tutorials for covering topics like pagination, fragment variables, etc although the further we get, the more framework-specific the content will have to be. I'm more than happy to put together a Houdini-flavored advanced section covering these topics if desired.

More concretely, content-wise, a single tutorial would have multiple "chapters". Each chapter would introduce a topic with some text and provide a directory of source code to provide a starting point with a panel that shows the rendered application. There would also be a button for users that just want to see the "solution" which would load a pre-defined file system. Once the user achieves the goal outlined by the introduction text, we could then have more discussion about that end state. Potentially providing line-specific highlighting so correlating across the moving parts is easier. That will require overwriting their content with our desired end state (which impacts the ability to string one body of work across multiple chapters) but maybe that's an okay compromise for a specific tutorial.