graphql / graphql/graphql.github.io
tutorials need improvement
まだ誰も着手していません。
- 主要言語
- TypeScript
- スター
- 889
- フォーク
- 1.5k
- 平均マージ
- 4日 12時間
- マージ済み PR(30日)
- 21
説明
Description
I tried the first three JS tutorials on your site, and they all failed the first time.
Steps to Reproduce
A
- go to https://graphql.org/code/.
- Do the GraphQL.js demo; copy/paste in contents as shown to hello.js
- node hello.js # gets error messages
- Nothing telling me to create an NPM project! Can't import anything.
B
- set up an NPM project named 'graphql_try1':
- mkdir graphql_try1; cd graphql_try1; npm init # then answer questions
- npm i
- go to https://graphql.org/code/. Create hello.js
- node hello.js # finally it runs, but the output is kindof cryptic and there's no explanation
C
- Use same project.
- go to https://graphql.org/code/ again, but this time do the Apollo tut.
- node server.js
- errors because type: is not set to module in package.json . This needs to be explained in the tut.
- node server.js
- seems to do nothing
D
- go back to hello.js and try that:
- node hello.js
- Fails now because mode: set to module. All these error messages are pretty discouraging.
E
- Go to https://graphql.org/learn/, supposedly the Introduction.
- 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:
- mkdir gq_try1
- cd gq_try1
- npm init
- answer questions - use gq_try1 as the project name; the rest, just hit return
- ...
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.
コントリビューションガイド
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
調査の方向性
まず、クリーンな Node.js および npm のセットアップから https://graphql.org/code/ の GraphQL.js と Apollo のチュートリアル、および https://graphql.org/learn/ の入門を確認します。記載されているコマンドとエラーを再現し、その後チュートリアルを更新して、セットアップ手順、モジュール設定、期待される出力、クライアント/サーバーのコンテキストを説明し、例が最初から最後まで動作するようにします。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- javascript, node.js
- 領域
- documentation
- issue の種類
- ドキュメント
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 活発さ
- 停滞
- 明瞭さ
- 説明が足りない
- 初心者へのやさしさ
- 35/100