continue rearranging deploy markers content

Author: rosieyohannan

docs/guides/modules/deploy/pages/configure-deploy-markers.adoc

@@ -16,12 +16,31 @@ For a full guide to CircleCI's deploys features and functionality, refer to the
 * A CircleCI account connected to your code. You can link:https://circleci.com/signup/[sign up for free].
 * A CircleCI project with a workflow configured to deploy your code.
 
-== 1. Update the configuration
+== 1. Create an envrionment
+
+Our first step is to create an environment and component for your deployment. You can choose to skip this step if either of the following is true:
+
+* You already have an environment set up in your organization.
+* You are happy for CircleCI to automatically create an environment with the name `default` and a component with the name of your project.
+
+=== 1.1 Create an environment integration
+
+. In the link:https://app.circleci.com[CircleCI web app], select your org from the org cards on your user homepage.
+. Select **Deploys** in the sidebar.
+. Select the **Environments** tab.
+. Select btn:[Create Environment Integration].
+. Enter a name for your environment, and a description if you would like.
+. Use the dropdown menu to choose your environment integration type. Choose the "Custom" option to follow along with this guide,. If you are deploying to your Kubernetes cluster you can or if you want to use the CircleCI release agent, then choose "Kubernetes Cluster" and head over to the xref:set-up-circleci-deploys.adoc[Release agent setup] page.
+. Select btn:[Save and Continue].
+
+=== 1.2
+
+== 2. Update the configuration
 
 To create a deployment marker, you will update your CircleCI configuration file.
 You will add commands to plan a deploy and then update its status based on the outcome of your deployment script.
 
-=== 1.1. Plan a deploy
+=== 2.1. Plan a deploy
 
 Add a `circleci run release plan` command to your deployment job. This tells CircleCI to plan a new deploy and show it in the link:https://app.circleci.com/deploys[Deploys UI] with `pending` status.
 
@@ -48,12 +67,12 @@ jobs:
   deploy-my-service:
     executor: some-executor
     steps:
-      - run: circleci run release plan --environment-name=<some-environment-name> --component-name=<some-component-name> --target-version=<some-version-name> --namespace=<some-namespace>
+      - run: circleci run release plan <deploy-name> --environment-name=<some-environment-name> --component-name=<some-component-name> --target-version=<some-version-name> --namespace=<some-namespace>
 ----
 
 In this example, note the following:
 
-** The `environment-name` parameter sets the target environment. If the specified environment does not exist, it will be created.
+** The `environment-name` parameter sets the target environment. If the specified environment does not exist, it will be created and named `default`.
 ** The `component-name` parameter sets the name that will be displayed in the Deploys UI.
 ** The `namespace` parameter is optional and can be provided to use a value other than `default`.
 
@@ -73,7 +92,7 @@ jobs:
 In the example the positional argument `deploy-name` is the arbitrary value that will be used to identify the deployment and should be unique within the workflow.
 If not specified, the deployment name will be set to `default`.
 
-=== 1.2. Update the deploy status
+=== 2.2. Update the deploy status
 
 After deploying your application, you can update the status of the deployment to `RUNNING` by running the `circleci run release update` command in a new step.
 
@@ -144,7 +163,7 @@ echo "FAILURE_REASON='Deployment was not found'" > failure_reason.env
 
 CAUTION: Trying to update the status of the deploy after updating it to a terminal status such as `SUCCESS`, `FAILED` or `CANCELED` is not supported and will result in an error.
 
-=== 1.3 Update the deploy status to canceled
+=== 2.3 Update the deploy status to canceled
 
 If you want to update your deployment to `canceled` when the deploy job is canceled, you can do so by adding the following job to your configuration.
 
@@ -181,7 +200,7 @@ workflows:
 
 This will make it sot that the job will be run only when the `deploy` job is canceled, thus updating the deployment to the `canceled` status.
 
-=== 1.4. Full config example
+=== 2.4. Full config example
 
 For reference, here is a full example of a CircleCI config that makes use of the deployment tracking feature.
 
@@ -240,7 +259,7 @@ workflows:
               - canceled
 ----
 
-== 2. Deploy logs
+== 3. Deploy logs
 
 Sometimes you might not want your deployment marker to have any specific status, but still want it to be logged in the deploys UI.
 In those cases you can use the `release log` command in place of `release plan` as shown in the example below.
@@ -278,20 +297,6 @@ jobs:
 ** (Optional) You can provide the following parameter if required:
 *** The `namespace` parameter can be provided to use a value other than `default`.
 
-[#manage-environments]
-== 3. Manage environments
-
-Configuring deploy markers will automatically create an environment integration in the link:https://app.circleci.com/deploys[CircleCI deploys UI] with the name you specified or with the `default` name if you didn't specify any.
-You can then use the link:https://app.circleci.com/deploys/github/circleci#environments[CircleCI UI] to manage your environments, by creating, deleting or updating them.
-To manually create an environment integration, follow these steps:
-
-. In the CircleCI web app, select **Deploys** in the sidebar.
-. If this is your first environment setup, select btn:[Create your first Environment Integration]. If you already have environments set up, choose the **Environments** tab and select btn:[Create Environment Integration].
-. Enter a name for your environment, and a description if you would like.
-. Use the dropdown menu to choose your environment integration type, then select btn:[Next: Release Agent Setup].
-If you plan to only use deploy markers, as opposed to the Kubernetes agent, feel free to choose the `custom` type.
-**You do not need to continue with installing a release agent at this point**, but you will need to reference this environment integration name as part of your config when adding the `log release` step below.
-
 == Manual configuration of automatically detected deploys
 
 If you have some link:https://circleci.com/changelog/auto-generated-deploy-markers-are-being-sunset/[automatically detected deploy markers] you can consider manually configuring them. CircleCI no longer automatically creates deploy markers for you.