Editorial

Author: leebyron

spec/Section 1 -- Overview.md

@@ -63,7 +63,7 @@ GraphQL has a number of design principles:
   endpoints. A GraphQL response, on the other hand, contains exactly what a
   client asks for and no more.
 
-- **Introspective**: GraphQL is introspective and self-describing. A GraphQL
+- **Self-describing**: GraphQL is self-describing and introspective. A GraphQL
   service's type system can be queryable by the GraphQL language itself, which
   includes readable documentation. GraphQL introspection serves as a powerful
   platform for building common developer tools and client software libraries.

spec/Section 2 -- Language.md

@@ -237,13 +237,13 @@ defined by this specification.
 
 Description : StringValue
 
-Documentation is a first-class feature of GraphQL by encouraging written
+Documentation is a first-class feature of GraphQL by including written
 descriptions on all named definitions in executable {Document} and GraphQL type
 systems, which is also made available via introspection ensuring the
 documentation of a GraphQL service remains consistent with its capabilities (see
 [Type System Descriptions](#sec-Type-System-Descriptions)).
 
-GraphQL descriptions are expected to provided as Markdown (as specified by
+GraphQL descriptions are provided as Markdown (as specified by
 [CommonMark](https://commonmark.org/)). Description strings (often
 {BlockString}) occur immediately before the definition they describe.
 
@@ -279,11 +279,10 @@ fragment TimeMachineDetails on TimeMachine {
 }
 ```
 
-Descriptions and comments in executable GraphQL documents are purely for
-documentation purposes. They MUST NOT affect the execution, validation, or
-response of a GraphQL document except for type introspection. It is otherwise
-safe to remove all descriptions and comments from executable documents without
-changing their behavior or results.
+Descriptions in GraphQL executable documents are purely for documentation
+purposes. They MUST NOT affect the execution, validation, or response of a
+GraphQL document. It is safe to remove all descriptions and comments from
+executable documents without changing their behavior or results.
 
 ## Document
 

spec/Section 6 -- Execution.md

@@ -35,9 +35,9 @@ chosen by the implementing service.
 
 Note: Descriptions and comments in executable documents (operation definitions,
 fragment definitions, and variable definitions) MUST be ignored during execution
-and have no effect on the execution, validation, or response of a GraphQL
-document. Descriptions and comments on executable documents MAY be used for
-observability and logging purposes.
+and have no effect on the observable execution, validation, or response of a
+GraphQL document. Descriptions and comments on executable documents MAY be used
+for non-observable purposes, such as logging and other developer tools.
 
 ## Executing Requests