graphql / graphql/graphql.github.io

Documentation about adding a mutation was hard to follow

オープン
#250 コメント 1 件 リアクション 1 件 担当者 0 名 GitHub で見る
✏️ Editorial 💬 Feedback
主要言語
TypeScript
スター
889
フォーク
1.5k
平均マージ
4日 12時間
マージ済み PR(30日)
21

説明

I was looking into how to add a "Create User" mutation to my graphql-js server. It took me a while to end up at the right code, so just documenting where I got confused:

1. Searched for "Mutation" on the site. There are two sections ostensibly about mutation:
a. http://graphql.org/learn/queries/#mutations
b. http://graphql.org/learn/schema/#the-query-and-mutation-types
1. Skimming each page, it was hard to figure out how to actually define a mutation in the schema. The code talking about mutations wasn't clear if it was showing how to do them in the query or in the schema.
1. I found the operative sentence is in (b): "Mutations work in a similar way - you define fields on the Mutation type, and those are available as the root mutation fields you can call in your query." and was able to write the correct schema:

```
input CreatePersonInput {
name: String
}
type Mutation {
createPerson(person: CreatePersonInput!): Person
}
```

Suggestions:
- I was thinking it would be better to just put an example of the schema changes necessary to make a mutation right into the schema (b) section to avoid confusion
- Make it clearer when a block of code in the docs is in GraphQL query language or schema language (maybe even show "Query" and "Response" labels next to the left and right sides)

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

まず graphql.org/learn/queries/#mutations と graphql.org/learn/schema/#the-query-and-mutation-types の mutations セクションを比較します。どの例がクエリ言語で、どの例がスキーマ言語なのかを明確にし、Create User mutation に必要な変更を示すスキーマ例を追加します。読者が両者を区別し、混乱せずにスキーマ定義を見つけられれば完了です。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
graphql
領域
documentation
issue の種類
ドキュメント
難易度
2/5
見積もり時間
1〜3時間
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
35/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。