Apply suggestions from code review

Co-authored-by: Heather Cloward <[email protected]>

docs/custom-plugins/extended-types.md

@@ -1,7 +1,7 @@
 # Type extensions in plugins
 
 Redocly CLI in its core has a type tree which defines the structure of the API definition.
-Redocly CLI then uses it to do type-aware traversal of OpenAPI Document.
+Redocly CLI then uses it to do a type-aware traversal of an OpenAPI definition.
 
 The type tree is built from top level `Types` which can link to child types. For example, here is a [visual reference to the OpenAPI types structure](../../openapi-visual-reference/openapi-node-types.md). You can also check [the code itself](https://github.com/Redocly/redocly-cli/tree/main/packages/core/src/types) for information about specific versions of OpenAPI and other supported document types.
 

docs/custom-plugins/index.md

@@ -8,27 +8,27 @@ redirectFrom:
 
 # Custom plugins
 
-Custom plugins are a powerful way to extend Redocly. Use of custom plugins requires requires in-depth knowledge of the document type (such as OpenAPI) that you are working with, JavaScript coding skills, and the plugin interface.
+Custom plugins are a powerful way to extend Redocly. Use of custom plugins requires in-depth knowledge of the document type (such as OpenAPI) that you are working with, JavaScript coding skills, and the plugin interface.
 Custom plugins are recommended for advanced users who have exhausted the built-in options available, and who can develop JavaScript extensions themselves.
 Each plugin is a JavaScript module which can export custom rules, configuration, preprocessors, decorators or type tree extensions.
 
 :::Info
-For many users, the highly [configurable rules](../rules/configurable-rules.md) covers their needs without needing a custom plugin.
+For many users, our highly [configurable rules](../rules/configurable-rules.md) cover their needs without needing a custom plugin.
 :::
 
 Custom plugins use the [visitor pattern](./visitor.md) to traverse the document structure and apply the rules and decorators (and preprocessors if you have them) to each element. Rules defined in custom plugins may need additional context available, and this can be achieved using the [nested visitor approach](./visitor.md#nested-visitors) (please note that nested visitors are not available for decorators or preprocessors).
 
 ## Extend Redocly with custom plugins
 
-The custom plugin functionality offers multiple ways to extend the built-in functionality of Redocly:
+Custom plugins can extend the built-in functionality of Redocly in the following ways:
 
-- **Write your own custom rules in JavaScript**. If your API standards include elements that can't be expressed by our existing rules, including configurable ones, you can code your own rules. See the [documentation on writing your own rules in custom plugins](./custom-rules.md).
+- **Write your own custom rules in JavaScript**. If your API standards include elements that can't be expressed by our existing rules, including configurable ones, you can code your own rules. See the [documentation on writing your own rules in custom plugins](./custom-rules.md) for more information.
 
-- **Define configuration in a custom plugin**. Redocly supports [resuable ruleset configuration](../guides/configure-rules.md#create-reusable-configuration) already, but defining configuration in a custom plugin is particularly useful when the configuration belongs alongside other plugin elements. See the [documentation on configuration in plugins](./custom-config.md).
+- **Define configuration in a custom plugin**. Redocly supports [resuable ruleset configuration](../guides/configure-rules.md#create-reusable-configuration) already, but defining configuration in a custom plugin is particularly useful when the configuration belongs alongside other plugin elements. See the [documentation on configuration in plugins](./custom-config.md) for more information.
 
 - **Extend existing standard definitions with additional type definitions**. Working with extensions to defined standards can be helped by [extending the supported types](./extended-types.md).
 
-- **Write custom decorators in JavaScript**. Not all API descriptions are exactly as we'd like them before passing them to the next stage of the API lifecycle. Redocly has a selection of [decorators available](../decorators), but if you need to build something more then [visit the documentation for building decorators in custom plugins](./custom-decorators.md).
+- **Write custom decorators in JavaScript**. Not all API descriptions are exactly as we'd like them to be before passing them to the next stage of the API lifecycle. Redocly has a selection of [decorators available](../decorators), but if you need to build something more then [visit the documentation for building decorators in custom plugins](./custom-decorators.md).
 
 
 ### Order of execution
@@ -63,7 +63,7 @@ The paths are relative to the configuration file location. Where there are multi
 
 ### Plugin structure
 
-The minimal plugin should export an `id` string that is used to refer to the contents of the plugin in configuration:
+The minimal plugin should export an `id` string that is used to refer to the contents of the plugin in the `redocly.yaml` configuration file:
 
 ```js
 module.exports = {
@@ -74,8 +74,8 @@ module.exports = {
 <a id="oas-major-versions"></a>
 ## Supported formats
 
-Everything that is exported from plugin relates to one of the supported document formats, such as OpenAPI v3. It is done by exporting an object containing a key-value mapping from a document format and version (`oas2` or `oas3` are supported) to an extension object (rules, preprocessors, decorators).
+Everything that is exported from a plugin relates to one of the supported document formats, such as OpenAPI v3. Plugins work by exporting an object containing a key-value mapping from a document format and version (`oas2` or `oas3` are supported) to an extension object (rules, preprocessors, decorators).
 
-Before processing the definition document Redocly CLI detects the document format and applies corresponding set of extensions.
+Before processing the definition document, Redocly CLI detects the document format and applies a corresponding set of extensions.
 
 

docs/custom-plugins/visitor.md

@@ -49,7 +49,7 @@ This works fine for most context-free rules which check basic things. If you nee
 
 ## Nested visitors
 
-Visitor object (if it is not `any` or `ref`) can define [nested visitors](#nested-visitors).
+The visitor object (if it is not `any` or `ref`) can define [nested visitors](#nested-visitors).
 
 Here is a basic example of a nested visitor:
 
@@ -71,7 +71,7 @@ The `Schema` **visitor function** is called by Redocly CLI only if the Schema Ob
 
 As the third argument, `enter()` in a **nested visitor object** accepts the `parents` object with corresponding parent nodes as defined in the **visitor object**.
 
-<div class="attention"> It will be executed only for the first level of Schema Object.</div>
+<div class="attention"> It will be executed only for the first level of the Schema Object.</div>
 
 For the example document below:
 

docs/decorators.md

@@ -4,7 +4,7 @@ redirectFrom:
 ---
 # Decorators
 
-Decorators are a way of changing an API description during bundling. This can be useful for many use cases:
+Decorators are a way of changing an API description during bundling. This updating during bundling can be useful for the following use cases:
 
 * removing some endpoints from an OpenAPI description before publishing
 * updating description fields