graphql / graphql/graphql.github.io

Documentation about adding a mutation was hard to follow

Offen
#250 1 Kommentar 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen
✏️ Editorial 💬 Feedback
Vorherrschende Sprache
TypeScript
Sterne
889
Forks
1.5k
Ø Merge
4 T. 12 Std.
Gemergte PRs (30 T.)
21

Beschreibung

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)

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Start by comparing the mutations sections at graphql.org/learn/queries/#mutations and graphql.org/learn/schema/#the-query-and-mutation-types. Clarify which examples are query language versus schema language, and add a schema example showing the changes needed for a Create User mutation. Done means a reader can distinguish the two and find the schema definition without confusion.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
graphql
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

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