tutorials need improvement

[Allan Bonadio]

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
4. go to https://graphql.org/code/. Create hello.js
5. 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.

[Hugh Willson]

Thanks very much for the feedback @allan-bonadio! If you're up for contributing, we'd love the help. 🙇

[Abhishek Upadhyay]

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.

works fine

[Abhishek Upadhyay]

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

you need to set type:module if you want to use import statement in js file but after using that it shows this error now

[Abhishek Upadhyay]

@hwillson can u assign it me, i will be happy to help

[Benjie]

@Tweniee Feel free to just go ahead and raise a PR, no need to be assigned :)