Apply suggestions from code review

Co-authored-by: Matthew Borden <[email protected]>

pages/apis/graphql/cookbooks/rules.md

@@ -37,7 +37,6 @@ Get the first 10 rules and their information for an organization:
       }
     }
   }
-  ```
 
 ## Create a rule
 

pages/apis/rest_api/rules.md

@@ -6,7 +6,7 @@ The rules API lets you create and manage rules in your organization.
 
 [Rules](/docs/pipelines/rules/overview) allow you to manage permissions between Buildkite resources.
 
-A rule is used to specify that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as cluster boundaries.
+A rule is used to specify that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline). Rules allow you to break out of the defaults provided by Buildkite such as the isolation between [clusters](/docs/clusters/overview).
 
 ### List rules
 

pages/pipelines/rules/manage_rules.md

@@ -40,7 +40,7 @@ where:
 
 <%= render_markdown partial: 'apis/descriptions/rest_pipeline_uuid' %>
 
-## Using the GraphQL API
+### Using the GraphQL API
 
 To [create a new rule](/docs/apis/graphql/schemas/mutation/rulecreate) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation:
 
@@ -113,7 +113,7 @@ where:
 
 <%= render_markdown partial: 'apis/descriptions/rest_rule_uuid' %>
 
-## Using the GraphQL API
+### Using the GraphQL API
 
 To [delete a rule](/docs/apis/graphql/schemas/mutation/ruledelete) using the [GraphQL API](/docs/apis/graphql-api), run the following example mutation:
 

pages/pipelines/rules/overview.md

@@ -4,7 +4,7 @@ Rules allow you to manage permissions between Buildkite resources.
 
 Rules express that an action is allowed between a source resource (e.g. a pipeline) and a target resource (e.g. another pipeline).
 
-Rules are typically used in tandem with [clusters](/docs/clusters/overview) to increase security and control, where clusters set hard boundaries and rules provide exceptions.
+Rules provide explicit access between resources, allowing granting or restricting access between resources that would normally be determined by the default permissions.
 
 ## Available rule types