graphql / graphql/graphql.github.io
tutorials need improvement
- Dominant language
- TypeScript
- Stars
- 889
- Forks
- 1.5k
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 21
Description
### Description
I tried the first three JS tutorials on your site, and they all failed the first time.
### Steps to Reproduce
A
1. go to https://graphql.org/code/.
2. Do the GraphQL.js demo; copy/paste in contents as shown to hello.js
3. node hello.js # gets error messages
4. Nothing telling me to create an NPM project! Can't import anything.
B
1. set up an NPM project named 'graphql_try1':
2. mkdir graphql_try1; cd graphql_try1; npm init # then answer questions
3. npm i
5. go to https://graphql.org/code/. Create hello.js
6. node hello.js # finally it runs, but the output is kindof cryptic and there's no explanation
C
1. Use same project.
2. go to https://graphql.org/code/ again, but this time do the Apollo tut.
3. node server.js
4. errors because type: is not set to module in package.json . This needs to be explained in the tut.
5. node server.js
6. seems to do nothing
D
1. go back to hello.js and try that:
2. node hello.js
3. Fails now because mode: set to module. All these error messages are pretty discouraging.
E
1. Go to https://graphql.org/learn/, supposedly the Introduction.
2. Typed in what it said, into a file. Doesn't seem to do anything.
### Expected Result
Should have worked, and should explain what's going on, and any little glitches that creep in over the years needs to be fixed. The tutorial should work given a vanilla machine; every step needs to be detailed. (This is why the tutorial example needs to be simple.)
### Actual Result
A
4. Nothing telling me to create an NPM project! Can't import anything.
B
6. node hello.js # finally it runs, but the output is kindof cryptic and there's no explanation
C
6. seems to do nothing
D
3. Fails now because mode: set to module. All these error messages are pretty discouraging.
E
2. Doesn't seem to do anything.
### Additional Context
My guess is that these tutorials are never tested.
You have to visualize a n00b user starting from a clean slate. Imagine they just learned npm and Node today, and they're now branching out. They don't know much about anything that's going on; much less how to fix error messages that pop up! Such a beginner can be paralyzed by such errors, even if you know they're easy to fix. It's the "first day on the job" problem - everything fails, even if you thought you did it right. So, make it as easy as falling off a barstool.
A tutorial should be foolproof from start to finish. Explain how to create a project; not a long, detailed explanation, but something quick that only does what the user needs to do, exactly, to follow the story. like this:
1. mkdir gq_try1
2. cd gq_try1
3. npm init
4. answer questions - use gq_try1 as the project name; the rest, just hit return
5. ...
Don't leave any options - this reader wants freedom from choice.
Meanwhile, isn't graphql a client/server package? Where's the client? Another thing the intro tutorial should do is provide a basis for the user's development. Not very useful if there's no browser to talk to.
I'm between jobs right now - maybe I can find the time to write it myself.
Contributor guide
Assessment
This issue has not been assessed yet.