graphql / graphql/graphql.github.io

Documentation about adding a mutation was hard to follow

Abierto
#250 1 comentario 1 reacción 0 asignados Ver en GitHub
✏️ Editorial 💬 Feedback
Lenguaje dominante
TypeScript
Estrellas
889
Forks
1.5k
Merge medio
4 d 12 h
PR fusionados (30 d)
21

Descripción

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)

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

Comienza comparando las secciones sobre mutations en graphql.org/learn/queries/#mutations y graphql.org/learn/schema/#the-query-and-mutation-types. Aclara qué ejemplos corresponden al lenguaje de consultas y cuáles al lenguaje de esquemas, y añade un ejemplo de esquema que muestre los cambios necesarios para una mutation Create User. Se considerará terminado cuando un lector pueda distinguir ambos y encontrar la definición del esquema sin confusión.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
graphql
Área
documentation
Tipo de issue
Documentación
Dificultad
2/5
Tiempo estimado
1-3 horas
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
35/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.