1534-review-guide-for-replacing-servers (#1542)

* Removed header numbering, removed "We do" admonition, improved language for consistency.

* Cleaned up markdownlint and vale errors

* Cleaned up markdown

* Ran Prettier

* Apply suggestions from code review

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

* docs: Revert changes to package files

* Update docs/guides/replace-servers-url.md

Co-authored-by: Andrew Tatomyr <andrew.tatomyr@redocly.com>

* Update replace-servers-url.md

Included changes from comments

* Extended intro, added subheadings to "Verify the output", added a summary and resources

* docs: Prettier being fussy

---------

Co-authored-by: Lorna Jane Mitchell <github@lornajane.net>
Co-authored-by: Heather Cloward <heathercloward@gmail.com>
Co-authored-by: Lorna Mitchell <lorna.mitchell@redocly.com>
Co-authored-by: Andrew Tatomyr <andrew.tatomyr@redocly.com>

docs/guides/replace-servers-url.md

@@ -2,13 +2,13 @@
 
 Redocly allows you to use [custom decorators](../custom-plugins/custom-decorators.md) to modify content in the API description during the bundling process.
 
+You can use this method to create multiple instances of an API description file from a single source, each with a different server. For example, you can have separate API descriptions configured with your mock server and your production server, or separate API files for each of your customers.
+
 This page describes how to replace the server URL with a decorator for a given environment.
 
 ## Prerequisites
 
-{% admonition type="note" name="We do, You do" %}
+- [Install @redocly/cli](../installation.md). We use version 1.12.0 in this tutorial.
-This tutorial is most effective when you follow along and complete the steps.
-{% /admonition %}
 
 - [Install @redocly/cli](../installation.md) with version 1.0.0-beta.111 or later (we use 1.0.0-beta.111 in this tutorial).
 - Save the following OpenAPI file as `original.yaml` into a new directory named `replace-servers-demo`.
@@ -34,13 +34,44 @@ This tutorial is most effective when you follow along and complete the steps.
   ```
 - Use your favorite IDE for editing files (we use VS Code and have the [Redocly extension](https://redocly.com/docs/redocly-openapi/) installed).
 
-## Step 1: Create a custom plugin
+## Create a demo folder and description file
+
+Before you start, create a demo folder and a sample OpenAPI description file to later test your plugin and decorators.
+
+1. Create a new folder and name it `replace-servers-demo`.
+
+2. In the `replace-servers-demo` folder, create an `original.yaml` file with the following content:
+
+```yaml
+openapi: 3.1.0
+    info:
+      version: 1.0.0
+      title: Custom decorators demo
+      description: The servers URL is replaced by the decorator during the `bundle` process.
+servers:
+  - url: 'https://example.com/api/v1'
+paths:
+  /status:
+    get:
+      summary: Get status
+      operationId: getStatus
+      security: []
+      responses:
+        '204':
+          description: Status OK
+        '400':
+          description: Status not OK
+```
+
+3. Save the file.
+
+## Create a custom plugin
 
 In this step, create a custom plugin and define the decorator dependency.
 
-1. Create a directory called `plugins`.
+1. In the `replace-servers-demo` folder, create a folder called `plugins`.
 
-2. Create a `plugin.js` file inside of the `plugins` directory with this information.
+2. In the `plugins` folder, create a `plugin.js` file with this code:
 
 ```JavaScript
 const ReplaceServersURL = require('./decorators/replace-servers-url');
@@ -62,15 +93,16 @@ module.exports = {
 3. Save the file.
 
 {% admonition type="attention" %}
-You can name the plugins directory and file anything you want. Make sure you use the correct name in the Redocly configuration file (Step 3).
+If you change the names of the plugins directory or the files, make sure to change them also in the Redocly configuration file [when registering your plugins and decorators](#add-a-decorator-and-associate-it-with-an-environment-variable).
 {% /admonition %}
 
-## Step 2: Add a decorator and associate it with an environment variable
+## Add a decorator and associate it with an environment variable
 
 In this step, add a decorator and define the environment variable associated with it.
 
-1. Create a directory `decorators` inside of the `plugins` directory.
+1. Inside the `plugins` folder, create a `decorators` folder.
-1. Create a `replace-servers-url.js` file with this information and save it inside of the `decorators` directory.
+
+2. In the `decorators` folder, create a `replace-servers-url.js` file with this code:
 
 ```JavaScript
 module.exports = ReplaceServersURL;
@@ -92,13 +124,17 @@ function ReplaceServersURL({serverUrl}) {
 };
 ```
 
+3. Save the file.
+
 {% admonition type="attention" %}
-You can name the decorators directory anything you want. Make sure you use the correct directory name in line 1 of the `plugin.js` file (Step 1).
+If you change the name of the decorators directory, make sure to also change it in line 1 of the [`plugin.js` file](#create-a-custom-plugin).
 {% /admonition %}
 
-## Step 3: Configure the plugin for use
+## Configure the plugin for use
 
-To use the decorator, register your plugin in your Redocly configuration file. Register your `plugins` and `decorators`.
+To use the decorators, register your `plugins` and `decorators` in the [Redocly configuration file](../configuration/index.md).
+
+- In your Redocly configuration file, register your plugins and decorators:
 
 ```yaml
 apis:
@@ -118,15 +154,17 @@ extends:
   - recommended
 ```
 
-## Step 4: Verify the output
+## Verify the output
 
-The following command bundles the `original.yaml` API with the "backend" server URL.
+### Check the configuration for the "backend" server
 
-```yaml
+1. Run the following command to bundle the `original.yaml` API with the "backend" server URL.
+
+```shell
 npx @redocly/cli bundle sample@v1-backend
 ```
 
-The output should show the correct server URL.
+2. Verify that the output shows the correct server URL.
 
 ```yaml
 openapi: 3.1.0
@@ -139,13 +177,15 @@ servers:
 # ...
 ```
 
-The following command bundles the `original.yaml` API with the "proxy" server URL.
+### Check the configuration for the "proxy" server
 
-```yaml
+1. Run the following command bundles the `original.yaml` API with the "proxy" server URL.
+
+```shell
 npx @redocly/cli bundle sample@v1-proxy
 ```
 
-The output should show the correct server URL.
+2. Verify that the output shows the correct server URL.
 
 ```yaml
 openapi: 3.1.0
@@ -157,3 +197,17 @@ servers:
   - url: https://proxy.example.com/v1
 # ...
 ```
+
+## Summary
+
+In this tutorial you have created a plugin and a decorator that replace the server URL with one of the URLs defined in the Redocly configuration file.
+
+You now have two API description files, each configured to send requests to different servers.
+
+## What's next?
+
+You can reuse the code from your demo files and modify it to fit your API documentation.
+
+For more custom plugins, configuration, and other resources, see the [Redocly CLI Cookbook](https://github.com/Redocly/redocly-cli-cookbook).
+
+For the latest Redocly news and articles, visit our [blog](https://redocly.com/blog/).