PCX-1086 Fix article on exploring schema

Author: aaron-ruby-df

products/analytics/src/content/graphql-api/getting-started/explore-graphql-schema.md

@@ -3,48 +3,61 @@ title: Explore the GraphQL schema
 order: 40
 ---
 
-# Explore the GraphQL schema in the GraphQL client
+# Explore the GraphQL schema in the GraphiQL client
+
+One of the great features of a GraphQL API is that it offers "introspection"—you can explore the graph (by making API calls) to see the available data sets, the fields and their types, and the operations you can perform.
+
+_GraphiQL_ uses this functionality to provide a "Documentation Explorer" that you can use to understand the schema. Click on the _Docs_ link on the right-hand side and then drill down starting with `query` and proceeding to `viewer` and then `zone`. Introspection is also used to provide query auto-complete and syntax validation.
 
 You can explore the schema of the Coudflare GraphQL endpoint in the the GraphQL client. The examples below use the GraphiQL client.
 
 Before you begin, configure the API endpoint and HTTP headers in the GraphQL client.
 
-Click **Docs** to open the _Documentation Explorer_ pane.
+## Use the Documentation Explorer
+
+Click **Docs** to open the **Documentation Explorer** pane.
 
 A list of available nodes displays. The nodes in the list follow this syntax:
 
 ```
 node-name: node-type-definition
 ```
 
-Click on the _type definition_ of a node to view the fields that it provides. The _Documentation Explorer_ pane also displays descriptions of the nodes.
+## Find the type definition of a node
 
-When you first open the _Documentation Explorer_ pane, the **mutation** and **query** nodes display:
+When you first open the **Documentation Explorer** pane, the **mutation** and `query` nodes display:
 
 ![Mutation and query nodes](../../static/images/docs-query.png)
 
-* **query** is the name of the node.
-* **Query** is the type definition of the node.
+In this example `query` is the name of the node, and `Query` is the type definition of the node.
+
+## Find the fields available for a given type definition
 
-Click the **Query** type definition. The _Documentation Explorer_ panel displays the fields that the **query** node provides: **cost** and **viewer**.
+Click on the _type definition_ of a node to view the fields that it provides. The **Documentation Explorer** pane also displays descriptions of the nodes.
+
+Click the Query type definition. The **Documentation Explorer** panel displays the fields that the `query` node provides. In this example, the fields are `cost` and `viewer`.
 
 ![Cost and viewer fields](../../static/images/docs-viewer.png)
 
-Click on the type definition of **viewer** to list the fields of the **viewer** node. The **viewer** node fields include nodes that allow you to query **accounts** or **zones** data:
+## Find the arguments associated with a field
+
+Click on the type definition of the `viewer` field to list its sub-fields. The `viewer` field provides sub-fields that allow you to query `accounts` or `zones` data:
 
 ![viewer fields](../../static/images/docs-zone-filter.png)
 
-The **accounts** and **zones** nodes take arguments to specify what data set to query.
-For the **zones** node you can provide a **filter** of **ZoneFilter_InputObject** type. To view the fields to specify in the filter, click **ZoneFilter_InputObject**.
+The `accounts` and `zones` fields take arguments to specify what data set to query.
+
+For the `zones` node you can provide a filter of ZoneFilter_InputObject type. To view the fields to specify in the filter, click **ZoneFilter_InputObject**.
+
+To limit the amount of search results that the query returns, click the **limit** argument.
 
-To limit the amount of search results that the query returns, click **limit**.
+## Find the search nodes available for a zone
 
-To view a list of the fields within a zone, click on the **zones** type definition after the colon in the **zones** field:
+To view a list of the search nodes available for a zone, click on the `zones` type definition after the colon (`:`) in the `zones` field:
 
 ![Zones type definition](../../static/images/docs-zone.png)
 
-A list of _search nodes_ appears, with a brief description of their behavior and a list of valid arguments.
-Arguments that end with an exclamation mark ("!") are required.
+A list of **search nodes** appears, with a brief description of their behavior and a list of valid arguments. Arguments that end with an exclamation mark (`!`) are required.
 
 ![Search nodes](../../static/images/docs-fw-data-set.png)
 

products/analytics/src/content/graphql-api/getting-started/querying-basics.md

@@ -40,11 +40,14 @@ query{
 }
 ```
 
-## Example Query
+### Example Query
 
 The following query searches data from a zone for firewall events that occurred during a time interval. It sorts the results, limits the amount of results returned, and displays a set of fields for each firewall event.
 
 ```json
+---
+header: Query Firewall events for a specific time interval
+---
 query
 {
   viewer
@@ -80,6 +83,9 @@ query
 You can send the query with an API call or by clicking **Play** in the GraphiQL client. The format of the response is in JSON:
 
 ```json
+---
+header: Query response from firewallEventsAdaptive
+---
 {
   "data": {
     "viewer": {
@@ -109,11 +115,14 @@ You can send the query with an API call or by clicking **Play** in the GraphiQL
 }
 ```
 
-## Example Query showing two sets of data
+## Querying two data sets in a single API call
 
-This example query shows a range of GraphQL functionality. Two data sets for the specified zone are queried simultaneously, filters and aggregations are applied, and a limit is set on the number of records returned (note that you must include the `limit` argument, which can be equal or up to 10,000).
+This example query employs a broad range of GraphQL functionality. The example queries two data sets for the specified zone simultaneously, applies filters and aggregations, and sets a limit on the number of records returned. (Note that you must include the `limit` argument, which can be equal or up to 10,000.)
 
-```code
+```json
+---
+header: Query two data sets simultaneously
+---
 query {
   viewer {
     zones(filter: {zoneTag: "<your zone ID>"}) {
@@ -148,7 +157,11 @@ This is only an example. You must specify the <code>zoneTag</code> for your doma
 
 </Aside>
 
-How can you tell what data sets, metrics, dimensions, operators, and functions are available? One of the great features of a GraphQL API is that it offers "introspection": you can explore the graph (by making API calls) to see the available data sets, the fields and their types, and the operations you can perform. _GraphiQL_ users this functionality to provide a "Documentation Explorer" that you can use to understand the schema. Click on the _Docs_ link on the right-hand side and then drill down starting with `Query` and proceeding to `viewer` and then `zone`. Introspection is also used to provide query auto-complete and syntax validation.
+## Introspection
+
+One of the great features of a GraphQL API is that it offers "introspection"—you can explore the graph (by making API calls) to see the available data sets, the fields and their types, and the operations you can perform. 
+
+_GraphiQL_ users this functionality to provide a "Documentation Explorer" that you can use to understand the schema. Click on the _Docs_ link on the right-hand side and then drill down starting with `Query` and proceeding to `viewer` and then `zone`. Introspection is also used to provide query auto-complete and syntax validation.
 
 ## Helpful Resources