Apply suggestions from code review

Co-authored-by: Nathan Bower <[email protected]>
Signed-off-by: Naarcha-AWS <[email protected]>

DEVELOPER_GUIDE.md

@@ -1,11 +1,11 @@
 # Developer guide
  - [Introduction](#introduction)
  - [Starting the Jekyll server locally](#starting-the-jekyll-server-locally)
- - [Using spec-insert Jekyll plugin](#using-spec-insert-jekyll-plugin)
-   - [Insert Query Parameters](#insert-query-parameters)
-   - [Insert Path Parameters](#insert-path-parameters)
-   - [Insert Paths and HTTP Methods](#insert-paths-and-http-methods)
-   - [Ignored files and folders](#ignored-files-and-folders)
+ - [Using the spec-insert Jekyll plugin](#using-the-spec-insert-jekyll-plugin)
+   - [Inserting query parameters](#inserting-query-parameters)
+   - [Inserting path parameters](#inserting-path-parameters)
+   - [Inserting paths and HTTP methods](#inserting-paths-and-http-methods)
+   - [Ignoring files and folders](#ignoring-files-and-folders)
    - [CI/CD](#cicd)
 
 ## Introduction
@@ -17,15 +17,15 @@ You can run the Jekyll server locally to view the rendered HTML pages using the
 
 1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) 3.1.0 or later for your operating system.
 2. Install the required gems by running `bundle install`.
-3. Run `bundle exec jekyll serve` to start the Jekyll server locally. (This can take several minutes to be ready.)
+3. Run `bundle exec jekyll serve` to start the Jekyll server locally (this can take several minutes to complete).
 4. Open your browser and navigate to `http://localhost:4000` to view the rendered HTML pages.
 
 ## Using the `spec-insert` Jekyll plugin
-The `spec-insert` Jekyll plugin is used to insert API components into the markdown files. The plugin downloads the [latest OpenSearch Specification](https://github.com/opensearch-project/opensearch-api-specification) and renders the API components from the spec. This aims to reduce the manual effort required to keep the documentation up-to-date.
+The `spec-insert` Jekyll plugin is used to insert API components into Markdown files. The plugin downloads the [latest OpenSearch specification](https://github.com/opensearch-project/opensearch-api-specification) and renders the API components from the spec. This aims to reduce the manual effort required to keep the documentation up to date.
 
 To use this plugin, make sure that you have installed Ruby 3.1.0 or later and the required gems by running `bundle install`.
 
-Edit your markdown file and insert the following snippet where you want an API component to be rendered:
+Edit your Markdown file and insert the following snippet where you want render an API component:
 
 ```markdown
 <!-- spec_insert_start 
@@ -40,18 +40,18 @@ Everything between the `spec_insert_start` and `spec_insert_end` tags will be ov
 <!-- spec_insert_end -->
 ```
 
-Then run the follow Jekyll command to render the API components:
+Then run the following Jekyll command to render the API components:
 ```shell
 bundle exec jekyll spec-insert
 ```
 
-If you are working on multiple markdown files and do not want to keep running the `jekyll spec-insert` command, you can add the `--watch` (or `-W`) flag to the command to watch for changes in the markdown files and automatically render the API components:
+If you are working on multiple Markdown files and do not want to keep running the `jekyll spec-insert` command, you can add the `--watch` (or `-W`) flag to the command to watch for changes in the Markdown files and automatically render the API components:
 
 ```shell
 bundle exec jekyll spec-insert --watch
 ```
 
-Depending on the text editor you are using to edit the markdown, you may need to manually reload the file from disk to see the changes applied by the plugin if the editor does not automatically reload the file periodically.
+Depending on the text editor you are using, you may need to manually reload the file from disk to see the changes applied by the plugin if the editor does not automatically reload the file periodically.
 
 The plugin will pull the newest OpenSearch API spec from its [repository](https://github.com/opensearch-project/opensearch-api-specification) if the spec file does not exist locally or if it is older than 24 hours. To tell the plugin to always pull the newest spec, you can add the `--refresh-spec` (or `-R`) flag to the command:
 
@@ -61,7 +61,7 @@ bundle exec jekyll spec-insert --refresh-spec
 
 ### Inserting query parameters
 
-To insert query parameters table of the, use the following snippet:
+To insert the API query parameters table, use the following snippet:
 
 ```markdown
 <!-- spec_insert_start
@@ -71,7 +71,7 @@ component: query_parameters
 <!-- spec_insert_end -->
 ```
 
-This will insert the query parameters of the `cat.indices` API into the `.md` file with three default columns: `Parameter`, `Type`, and `Description`. There are 5 columns that can be inserted: `Parameter`, `Type`, `Description`, `Required`, and `Default`. When `Required`/`Default` is not chosen, the info will be written in the `Description` column.
+This will insert the query parameters of the `cat.indices` API into the `.md` file with three default columns: `Parameter`, `Type`, and `Description`. There are five columns that can be inserted: `Parameter`, `Type`, `Description`, `Required`, and `Default`. When `Required`/`Default` is not chosen, the information will be written in the `Description` column.
 
 You can customize the query parameters table with the following columns:
 
@@ -87,7 +87,7 @@ You can customize the query parameters table with the following columns:
 - `include_deprecated` (Boolean; default is `true`): Includes deprecated parameters in the table.
 - `pretty` (Boolean; default is `false`): Renders the table in the pretty format instead of the compact format.
 
-You can customize the query parameters table with the following columns:
+The following snippet inserts the specified columns into the query parameters table:
 
 ```markdown
 <!-- spec_insert_start
@@ -102,7 +102,7 @@ pretty: true
 
 ### Inserting path parameters
 
-To insert path parameters table of the `indices.create` API, use the following snippet:
+To insert the `indices.create` API path parameters table, use the following snippet:
 
 ```markdown
 <!-- spec_insert_start
@@ -112,11 +112,11 @@ component: path_parameters
 <!-- spec_insert_end -->
 ```
 
-This table behaves the same as the query parameters table except that it does not accept the `include_global` argument.
+This table behaves identically to the query parameters table except that it does not accept the `include_global` argument.
 
 ### Inserting paths and HTTP methods
 
-To insert paths and HTTP methods of the `search` API, use the following snippet:
+To insert paths and HTTP methods for the `search` API, use the following snippet:
 
 ```markdown
 <!-- spec_insert_start
@@ -132,4 +132,4 @@ The `spec-insert` plugin ignores all files and folders listed in the [./_config.
 
 ### CI/CD
 
-The `spec-insert` plugin is run as part of the CI/CD pipeline to ensure that the API components are up-to-date in the documentation. This is done through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Action workflow that creates a pull request with the updated API components every Sunday.
+The `spec-insert` plugin is run as part of the CI/CD pipeline to ensure that the API components are up to date in the documentation. This is performed through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Actions workflow, which creates a pull request containing the updated API components every Sunday.