Documentation about adding a mutation was hard to follow

[darknoon]

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
2. 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.
3. 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)

[StingyJack]

@carolstran if someone is going to be addressing these problems with the mutations, I have logged related issue #992 that they should be considering as well.