Improve docs of the GitLab docs site release process

2 files changed, 40 insertions, 61 deletions

diff --git a/.gitlab/issue_templates/release.md b/.gitlab/issue_templates/release.md
index 2ecc39b3..0a16b8a6 100644
--- a/.gitlab/issue_templates/release.md
+++ b/.gitlab/issue_templates/release.md
@@ -34,28 +34,46 @@ The following terms are used throughout this document:
    - [ ] `gitlab-runner`: <https://gitlab.com/gitlab-org/gitlab-runner/-/branches?state=all&sort=updated_desc&search=-stable>
    - [ ] `omnibus-gitlab`: <https://gitlab.com/gitlab-org/omnibus-gitlab/-/branches?state=all&sort=updated_desc&search=-stable>
    - [ ] `charts/gitlab`: <https://gitlab.com/gitlab-org/charts/gitlab/-/branches?state=all&sort=updated_desc&search=-stable> (Version number is 9 lower than `gitlab` release, so GitLab 16.X = Charts 7.X)
-1. [ ] When all the stable branches are available, [create a stable branch and Docker image for the release](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#create-stable-branch-and-docker-image-for-release):
 
-   1. [ ] In the root path of the `gitlab-docs` repository, update your local clone:
+1. [Create a stable branch and Docker image for the release](#create-a-stable-branch-and-docker-image-for-the-release).
 
-      ```shell
-      make update
-      ```
+#### Create a stable branch and Docker image for the release
 
-   1. [ ] Create the stable branch:
+> Note: an [issue exists](https://gitlab.com/gitlab-org/release-tools/-/issues/533)
+> to create the stable branch automatically.
 
-      ```shell
-      make create-stable-branch
-      ```
+1. [ ] In the root path of the `gitlab-docs` repository, update your local clone:
 
-      - A branch `X.Y` for the release is created.
-      - A new `X.Y.Dockerfile` is created and automatically committed.
-      - The new branch is pushed.
+   ```shell
+   make update
+   ```
+
+1. Optional. To practice running the task and check the process, run the Rake task in dry run mode:
+
+   ```shell
+   DRY_RUN=true make create-stable-branch
+   ```
+
+1. [ ] Create the stable branch:
+
+   ```shell
+   make create-stable-branch
+   ```
+
+   - A branch `X.Y` for the release is created.
+   - A new `X.Y.Dockerfile` is created and automatically committed.
+   - The new branch is pushed.
+
+   After the branch is created, the
+   [`image:docs-single` job](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/7fbb5e1313ebde811877044e87f444a0a283fed4/.gitlab/ci/docker-images.gitlab-ci.yml#L107-129)
+   runs and creates a new Docker image tagged with the name of the stable branch
+   (for example, see [the 15.6 release pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/702437095)).
+   When the job finishes, confirm the Docker image has been created. Go to the `registry` environment at
+   <https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry> and confirm the image
+   is listed.
+
+   In case the pipeline fails, see the [troubleshooting section](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#imagedocs-single-job-fails-when-creating-the-docs-stable-branch).
 
-      After the branch is created, the
-      [`image:docs-single` job](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/7fbb5e1313ebde811877044e87f444a0a283fed4/.gitlab/ci/docker-images.gitlab-ci.yml#L107-129)
-      runs and creates a new Docker image tagged with the name of the stable branch
-      (for example, see [the 15.6 release pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/702437095)).
 
 You can continue onto the next process immediately, or wait for the release post.
 
diff --git a/doc/releases.md b/doc/releases.md
index e7f828cf..66d55557 100644
--- a/doc/releases.md
+++ b/doc/releases.md
@@ -39,10 +39,11 @@ To minimize problems during the documentation release process, use the following
   1. If an issue was not already created for you by the TW that handled the last release,
      [create an issue for the release](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/new?issuable_template=release)
      to track your progress and ensure completeness.
-  1. Check the `#releases` Slack channel for a `This is the candidate commit to be released on the 22nd`
-     message. When the announcement is made, proceed with the next step.
-  1. [Create a stable branch and Docker image](#create-stable-branch-and-docker-image-for-release) for
-     the new version.
+  1. Check that the stable branches have been created in all 4 projects. For details, see "Check for
+     the stable branches that correspond with the release" in the docs release issue. When all
+     stable branches are available, proceed with the next step.
+  1. Create a stable branch and Docker image for the new version. For details, see "Create a stable
+     branch and Docker image for the release" in the docs release issue.
 
 - Complete the publication steps on the 22nd of the month, after the release post is live:
 
@@ -54,45 +55,6 @@ To minimize problems during the documentation release process, use the following
 
   If the 22nd of the month falls on a weekend or public holiday, it's OK to complete these publication steps on the next working day.
 
-## Create stable branch and Docker image for release
-
-> Note: an [issue exists](https://gitlab.com/gitlab-org/release-tools/-/issues/533)
-> to create the stable branch automatically.
-
-To create a stable branch of the `gitlab-docs` project and a Docker image for the release:
-
-1. Make sure you're in the root path of the `gitlab-docs` repository.
-1. Update your local checkout:
-
-   ```shell
-   make update
-   ```
-
-1. Optional. To practice running the task and check the process, run the Rake task in dry run mode:
-
-   ```shell
-   DRY_RUN=true make create-stable-branch
-   ```
-
-1. Run the make target to create the stable branch:
-
-   ```shell
-   make create-stable-branch
-   ```
-
-   A branch for the release is created, a new `X.Y.Dockerfile` is created and
-   automatically committed, and the new branch is pushed.
-
-After the branch is created, the
-[`image:docs-single` job](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/7fbb5e1313ebde811877044e87f444a0a283fed4/.gitlab/ci/docker-images.gitlab-ci.yml#L107-129)
-runs and creates a new Docker image tagged with the name of the stable branch
-(for example, see [the 15.6 release pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/702437095)).
-When the job finishes, confirm the Docker image has been created. Go to the `registry` environment at
-<https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry> and confirm the image
-is listed.
-
-In case the pipeline fails, see the [troubleshooting section](#imagedocs-single-job-fails-when-creating-the-docs-stable-branch).
-
 ### Optional. Test locally
 
 Prerequisite:
@@ -201,8 +163,7 @@ For example, if you released the 14.1 documentation, the first dropdown entry sh
 
 ### `compile_prod` job fails when creating the docs stable branch
 
-When you create the [stable branch](#create-stable-branch-and-docker-image-for-release),
-the `compile_prod` job might fail.
+When you create the stable branch in the `gitlab-docs` project, the `compile_prod` job might fail.
 
 This happens if stable branches have not been
 created for all the related projects. Some of the stable branches are