QuickStart Tutorial should be iterative

[facebook]

QuickStart Tutorial should be iterative

[revskill10]

👍
I would be happy if i could make one, like anyone here. Let's make this happen.

[steveluscher]

This is a great approach! I'll make it my job to iterate on the tutorial along these lines. Expect to see the tutorial, and the docs, evolve quite a bit over the next little while!

[cletusw]

Awesome! I'd love to stay involved throughout that process.

[gyzerok]

Awesome idea!

[steveluscher]

Based on some spectacular feedback from @BinaryMuse, @frantic, and others, here's what I'm thinking:

Split the tutorial into three acts: Hello GraphQL, Hello Relay, and Schema Building.

Hello GraphQL

Now that GraphiQL is open source, we should be able to drop it straight into the Relay docs, so that we can query a GraphQL schema interactively, and see the shape and content of the response immediately. Use the same schema that we use for the Hello Relay tutorial. My present thinking for what the schema should describe is a list of stories with comments & likes.

Hello Relay

Building upon a knowledge of how to write queries against a GraphQL endpoint, start to build a React app using Relay. First write enough code to query for a list of stories and display them. Next learn how to use calls by adding pagination. Next learn how to compose components and queries by adding comments below each story. Next, learn about mutations by adding the ability to create new comments. All of these activities should be possible to execute in-browser, using an interactive code editor and an in-memory schema.

Schema Building

The last piece is to lead someone through the creation of a custom schema. This will explain how to use the graphql-relay-js helpers, and in doing so should explain some core concepts like connections, cursors, and nodes. We might even consider punting on this section for the Relay website, since there have already been some excellent writeups on this topic from you: @clayallsopp [1] @davidchang [2] Rising Stack [3]. I have yet to see a Relay focussed one, so maybe there's still some work to do here.

I'm going to get started from the top. If you have thoughts or ideas, pen them down here!

[taion]

It might be worth considering the order of introducing basic schema building with introducing Relay mutations. When I was getting started, I got all of my "read" stuff set up before I did my first mutation, and I think I'm pretty happy I went with that path. Mutations are extremely powerful and amazing, but they seem "harder" to me in some sense than setting up the "read" paths on the schema.

[sgwilym]

One thing that I feel would be a shame to overlook in a tutorial is motivation: a succinct written roundup of some common frustrations that GraphQL and Relay solves would be a great boost for working through the tutorial and understanding why you need a Schema. Not being shy about pointing out these advantages when you've implemented them in the tutorial would be great too.

[enriquecaballero]

+1

[faassen]

I came in here to communicate that I think the tutorial needs serious work, and I found this issue. I got overwhelmed myself, and I had someone else communicate to me they got lost quickly themselves. Glad people are working on this. The guides themselves are much better, but if I'd just had to deal with the tutorial I'd have given up. The tutorial is unfortunately currently bad advertising for Relay. I'm going to give more constructive feedback next.

Splitting this into "intro to GraphQL", "intro to Relay client" and "how to build a Relay-compliant GraphQL schema" would be good. Some people who are looking to learn Relay are going to work with existing
GraphQL schemas and won't even need the latter tutorial. They are interested in the client-side only. And if I use some other implementation technology for the GraphQL server, such as Python, I'm not interested
in the JS details of that either.

I think the "Hello Relay" tutorial should focus on building a client-side app only against some existing GraphQL endpoint. It's fine if I get some kind of demo server installed or can point my code to an existing one on the web. It shouldn't go into how to construct the endpoint at all. I'm fine if this is done on the filesystem without in-browser magic. Benefits of just going for the filesystem:

• closer to the layout of real world projects that use Relay.
• it's also simpler to implement such a tutorial than something that's more fancy and uses in-browser editing facilities, etc. I think a better tutorial should be done quickly to limit further damage the current one does.

I also don't like the current tutorial approach where you take an existing project, ignore almost entirely what it is in it, and replace it with vast amounts of tutorial-specific code. I'm happy to explore the layout of an existing project, but I'd rather do it just checking that project out and reading source code comments that explain what it all does and points to further details elsewhere.

I like how @steveluscher separates multiple steps of the Relay tutorial:

• A UI that shows a list of stories.
• Pagination of stories. This shows off a core Relay feature quickly.
• Compose components and GraphQL fragments by adding comments below each story.
• Mutations. Creating new comments.

Each step should end in a fully working Relay project that doesn't require you to know about the next steps yet. There's nothing about the server implementation in any of this.

[xpepermint]

Big +1.

I think we need a step-by-step tutorials on how to create a GraphQL server + Relay/React client from scratch and we need a common example like list users + create new user. Everything above that is an overkill. At the moment it's difficult to start with all that new logic even for someone who is using node and react for quite some time. And we need this #206 issue to be resolved because this is where the confusion starts.
I would expect from a tutorial to have just 2 easy steps - first create a server using the express-graphql, then build relay component with a single GraphQL call. All that schema exporting and creating a plugin and complex schema structure, must be wrapped into some magic (as part of relay library that you include, then everything works out of the box). You can enable all that extra features for experts but 90+% of people won't use that.

[enriquecaballero]

Agreed and agreed.

[taion]

I'm reasonably happy with the content of the tutorial, BTW - I think in general it's not good to assume that a user already has access to a GraphQL server, and most people using Relay will need to build out their own GraphQL server, most likely with something plugging into graphql-js (and if not, most of the other APIs aren't meaningfully different semantically anyway).

In terms of depth, I also am pretty happy with how things look right now - compare for example the React tutorial, which also aims to go into relatively minimal depth.

I do think the structure can be improved, though. I think it'd be more clear if it presented:

1. Building the read-only parts of the GraphQL schema
   1. Optionally, using GraphiQL to interact with just the GraphQL server
2. Pulling data with Relay from the GraphQL server
3. Writing GraphQL mutations
4. Writing Relay mutations

That's pretty much the order in which I went through the tutorial, and I found it pretty good for explaining the concepts present in the tutorial.

Lastly, I'd consider providing a list of examples including what each example shows, just to help people who prefer looking at code over prose.

[taion]

BTW, I really like the approach e.g. here https://github.com/mtscout6/react-bootstrap-getting-started/tree/master with having master be the initial scaffolding for the tutorial, and subsequent steps being assigned to git tags.

[faassen]

@taion I think there are many cases where UI developers are using Relay without having to worry about the GraphQL server implementation, and more cases where developers may want to use another GraphQL server implementation altogether. For that reason, I much prefer a structure by @steveluscher, where schema building is deferred to the end. This way you serve both audiences: people who just want to use Relay on the client side, and people who are interested in building Relay-compliant server implementations.

If you have a big discussion about graphql-js with Relay extensions from the start, you risk losing part of the audience. You bury the lead on Relay too: Relay is about making it easier to develop UIs, and instead you distract people with a lot of stuff about server implementation requirements that may or may not be relevant to them, but what is in any case not the main selling point of Relay.

So @taion, since you're happy with the tutorial as is, do you think it would get worse if it followed a structure as suggested by @steveluscher?

[chandu0101]

I think there are many cases where UI developers are using Relay without having to worry about the GraphQL server implementation, and more cases where developers may want to use another GraphQL server implementation altogether

👍 , i am in same boat :)

[taion]

I don't know - to me, Relay and GraphQL are two sides of the same coin. Relay makes it easier to build UIs, yes, but what makes it better at building UIs than something like React Resolver or React Transmit are specifically the query patterns enabled by GraphQL. The real sell for Relay to me is not that "it lets me specify my data dependencies on each component", but that it lets me do so while still getting everything in a single round-trip, and likewise for mutations.

Those are really important reasons up front; they're hard to explain with a 5 minute pitch the way that React's "declarative UI" is very easy to understand, but it's an extremely important contrast to draw. DX matters, yes, but what's special about Relay is that it solves problems you just couldn't solve without GraphQL.

I think of a Relay tutorial that talks about containers before at least talking a little about schemas as being a little bit like a Flux tutorial that walks you through connecting to the stores before it talks about the stores themselves at all. I really think of my GraphQL server as partially moving what used to be my front-end data fetching into my back-end, so it makes a lot of sense for me to start with at least parts of the GraphQL schema, just to illustrate what's going on.

At least for the moment, someone planning on adopting GraphQL and Relay is much more likely to be in a position of already having an existing e.g. REST API to work with, rather than having an existing GraphQL API.

[faassen]

@taion Obviously a Relay tutorial needs to talk a bit about GraphQL, first, which is exactly what @steveluscher proposed. What it doesn't need to do first is talk about how to implement a server like that. You can show how to build a UI with an existing demo server. Your concern for those who want to work in a different order are easily taken care of by use of a paragraph somewhere on top of the Relay tutorial: "We are going to use a demo GraphQL server for the UI tutorial, but see if you want to skip ahead and see how you can build your own." That way what Relay is all about is focused on first. The "how to build your own" can then start saying "We're going to use this specific set of JS technologies, but see for alternatives."

The Relay project should not be in the business of explaining how to implement a full GraphQL server anyway: that's the job of the GraphQL project. It should only explain how you can make a GraphQL server Relay compliant, and it can use the JS reference implementations as examples.

[taion]

I agree that a Relay tutorial should not show how to set up a GraphQL server. Fortunately, the existing tutorial doesn't - it only shows you how to set up a schema.

The problem with a Relay tutorial that starts at Relay.createContainer without talking about building a schema is that it'd be like a Flux tutorial that talked about connecting to stores before talking about populating the stores! You could teach Flux that way, but I'm not aware that anybody does.

For a user considering Relay right now, this consideration most likely be in the context of considering GraphQL as well - if I'm not Facebook, I'm unlikely to have a GraphQL schema set up if I'm not planning on using Relay, and I can't use Relay without that GraphQL schema.

I really think the issue with the schema presentation is much more the how than the what. Relay users will have to know about nodes, connections, and mutations, but it's probably not necessary to show building all 3 before building my first component - that to me is what "iterative" means.

It's true that not everyone will be implementing their GraphQL server/schema in JS, but I think the choice of graphql-js makes perfect sense for a tutorial for a couple of reasons. First, the code demonstrated is sufficiently straightforward that differences to any other implementation are going to be more cosmetic than anything else. Second, anybody working through this tutorial is probably already familiar with JS, so graphql-js makes a good lingua franca for illustrating the basic concepts, without getting too much into implementation-specific details. Lastly, express-graphql is probably just the easiest way to get started with a real GraphQL server by a long shot (not counting something like relay-local-schema which is more for toys) - look at e.g. https://github.com/relayjs/relay-starter-kit/blob/b34f8a9bbee276af7697e6e0cdf8e0e766c72e95/server.js#L11-L16, which is literally 3 statements to get things up and running.

Something like setting up a full-fledged schema that connects to backend models should be considered out-of-scope for a Relay tutorial, just as connecting to a full-featured backend should be considered out-of-scope for a Flux tutorial. I think something like what's currently present, but presented in a more iterative manner, is a really good fit for demonstrating Relay + GraphQL as a system, and furthermore I think the appropriate introduction does need to touch a bit on both.

[taion]

A meta-point - who's the marginal consumer of this tutorial? Probably anybody who's a infra dev at FB or who has been involved in writing Relay- or GraphQL-related libraries already is right out.

[steveluscher]

I've been the assignee on this task for far too long with no action, so I'm going to put it back up for grabs. In the back of my mind, I've been wanting to take this code and parcel it out into the sections that I've outlined above, making use of the code injection features of /prototyping/graphiql.html and /prototyping/playground.html to embed interactive examples along the way (you can URL encode schema or app source code into the playground through the ?source=…&schema=… query params, and to GraphiQL using the ?schema=… query param).

I'll revisit this a few weeks, before time which I don't think I'll have time to knock it out.

[ryanblakeley]

In regards to schema building - I'm wondering how one might break up pieces (such as ObjectType definitions and Mutation definitions) into modules. It would be nice to see that done correctly in an example.

[wincent]

Going to close this out because we will be rebuilding the website/tutorial experience for the release of Relay 2. Thanks to everybody who provided input on this issue, as it is helpful in informing our understanding of how people new to the framework (and to GraphQL) approach the whole thing.