graphql / graphql/graphql.github.io

tutorials need improvement

Offen
#1,270 5 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
📌 Help wanted
Vorherrschende Sprache
TypeScript
Sterne
889
Forks
1.5k
Ø Merge
4 T. 12 Std.
Gemergte PRs (30 T.)
21

Beschreibung

### 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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Start by reviewing the GraphQL.js and Apollo tutorials at https://graphql.org/code/ and the introduction at https://graphql.org/learn/ from a clean Node.js and npm setup. Reproduce the listed commands and errors, then update the tutorials so setup steps, module configuration, expected output, and client/server context are explained and the examples work from start to finish.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
javascript, node.js
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Veraltet
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.