Incorporate feedback from glasser

Author: Stephen Barlow

docs/source/schema/directives.md

@@ -1,14 +1,14 @@
 ---
 title: Directives
 sidebar_title: Directives
-description: Configure schema types, fields, and arguments
+description: Configure GraphQL types, fields, and arguments
 ---
 
-A **directive** decorates part of a GraphQL document with additional configuration. Tools like Apollo Server (and [Apollo Client](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies/#querying)) can read a GraphQL document's directives and perform custom logic as appropriate.
+A **directive** decorates part of a GraphQL schema or operation with additional configuration. Tools like Apollo Server (and [Apollo Client](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies/#querying)) can read a GraphQL document's directives and perform custom logic as appropriate.
 
 Directives are preceded by the `@` character, like so:
 
-```graphql{2}
+```graphql{2}:title=schema.graphql
 type ExampleType {
   oldField: String @deprecated(reason: "Use `newField`.")
   newField: String
@@ -22,32 +22,44 @@ This example shows the `@deprecated` directive, which is a [default directive](#
 
 ## Valid locations
 
-Each directive's definition specifies _where_ it can appear in a GraphQL document. For example, here's the GraphQL spec's definition of the `@deprecated` directive:
+Each directive can only appear in _certain_ locations within a GraphQL schema or operation. These locations are listed in the directive's definition.
+
+For example, here's the GraphQL spec's definition of the `@deprecated` directive:
 
 ```graphql
 directive @deprecated(
   reason: String = "No longer supported"
 ) on FIELD_DEFINITION | ENUM_VALUE
 ```
 
-This indicates that `@deprecated` can decorate either a schema field definition (as shown in the example above) or an enum value definition (as shown here):
+This indicates that `@deprecated` can decorate either a `SCHEMA_FIELD` definition (as shown at the top of the article) or a schema `ENUM_VALUE` definition (as shown here):
 
-```graphql
+```graphql:title=schema.graphql
 enum MyEnum {
   OLD_VALUE @deprecated(reason: "Use `NEW_VALUE`.")
   NEW_VALUE
 }
 ```
 
-If `@deprecated` appears elsewhere in a GraphQL schema, it produces an error.
+If `@deprecated` appears elsewhere in a GraphQL document, it produces an error.
+
+> If you [create a custom directive](#creating), you need to define it (and its valid locations) in your schema. You don't need to define [default directives](#default-directives) like `@deprecated`.
+
+### Schema directives vs. operation directives
+
+Usually, a given directive appears _exclusively_ in GraphQL schemas or _exclusively_ in GraphQL operations (rarely both, although the spec allows this).
+
+For example, among the [default directives](#default-directives), `@deprecated` is a schema-exclusive directive and `@skip` and `@include` are operation-exclusive directives.
+
+The [GraphQL spec](https://spec.graphql.org/June2018/#sec-Type-System.Directives) lists all possible directive locations. Schema locations are listed under `TypeSystemDirectiveLocation`, and operation locations are listed under `ExecutableDirectiveLocation`.
 
 ## Default directives
 
 The [GraphQL specification](http://spec.graphql.org/June2018/#sec-Type-System.Directives) defines the following default directives:
 
 | Directive | Description |
 |-----------|-------------|
-| `@deprecated(reason: String)` | Marks the definition of a field or enum value as deprecated with an optional reason. |
+| `@deprecated(reason: String)` | Marks the schema definition of a field or enum value as deprecated with an optional reason. |
 | `@skip(if: Boolean!)` | If `true`, the decorated field or fragment in an operation is _not_ resolved by the GraphQL server. |
 | `@include(if: Boolean!)` | If `false`, the decorated field or fragment in an operation is _not_ resolved by the GraphQL server. |
 
@@ -63,7 +75,9 @@ You can extend Apollo Server with custom schema directives created by you or a t
 
 To use a custom directive, pass its associated `SchemaDirectiveVisitor` subclass to Apollo Server via the `schemaDirectives` argument. This object maps the name of a directive (e.g., `upper`) to the class that implements its behavior (e.g., `UpperCaseDirective`).
 
-```js{40-42}
+Also make sure the directive is defined in your schema with all valid locations listed.
+
+```js{20,40-42}
 const { ApolloServer, gql, SchemaDirectiveVisitor } = require('apollo-server');
 const { defaultFieldResolver } = require('graphql');