From edac34cf4f083e270ca0c35596796d50f6b612b0 Mon Sep 17 00:00:00 2001
From: Ashraf Khamis <akhamis@gitlab.com>
Date: Thu, 22 Jun 2023 11:19:55 +0000
Subject: [PATCH] Refactor docs for slash commands

---
 doc/ci/chatops/index.md                       | 14 ++---
 doc/integration/slash_commands.md             | 54 +++----------------
 doc/operations/incident_management/slack.md   |  2 +-
 doc/user/admin_area/moderate_users.md         |  4 +-
 .../integrations/gitlab_slack_application.md  | 42 +++++++--------
 .../integrations/mattermost_slash_commands.md | 23 +++-----
 .../integrations/slack_slash_commands.md      | 20 ++++---
 7 files changed, 55 insertions(+), 104 deletions(-)

diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md
index 7be12d0c0fd30..09f2758113f44 100644
--- a/doc/ci/chatops/index.md
+++ b/doc/ci/chatops/index.md
@@ -49,18 +49,20 @@ When the job runs:
 
 ## Run a CI/CD job
 
-You can run a CI/CD job from chat with the `/project-name run`
-[slash command](../../integration/slash_commands.md).
-
-Prerequisites:
+Prerequisite:
 
 - You must have at least the Developer role for the project.
 
-To run a CI/CD job:
+You can run a CI/CD job on the default branch from chat. To run a CI/CD job:
+
+- In the chat client, enter `/<project-name> run <job name> <arguments>` where:
 
-- In the chat client, enter `/project-name run <job name> <arguments>`.
+  - `<project-name>` is the name of the project.
+  - `<job name>` is the name of the CI/CD job to run.
+  - `<arguments>` is the arguments to pass to the CI/CD job.
 
 ChatOps schedules a pipeline that contains only the specified job.
+Other [slash commands](../../user/project/integrations/gitlab_slack_application.md#slash-commands) are also available.
 
 ### Exclude a job from ChatOps
 
diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md
index 02c7debc6dcbd..e36ee164002c2 100644
--- a/doc/integration/slash_commands.md
+++ b/doc/integration/slash_commands.md
@@ -1,51 +1,11 @@
 ---
-stage: Manage
-group: Import and Integrate
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
+redirect_to: '../user/project/integrations/gitlab_slack_application.md#slash-commands'
+remove_date: '2023-09-19'
 ---
 
-# Slash commands in Mattermost and Slack **(FREE)**
+This document was moved to [another location](../user/project/integrations/gitlab_slack_application.md#slash-commands).
 
-> [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) from GitLab Ultimate to GitLab Free in 11.9.
-
-If you want to control and view GitLab content while you're
-working in Slack and Mattermost, you can use slash commands.
-Type the command as a message in your chat client to activate it.
-For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md).
-
-Slash commands are scoped to a project and require
-a specified trigger command during configuration.
-You should use the project name as the trigger command.
-
-If you're using the [GitLab for Slack app](../user/project/integrations/gitlab_slack_application.md) for
-your GitLab.com projects, [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#slash-commands)
-(for example, `/gitlab <project-name> issue show <id>`).
-
-Assuming `project-name` is the trigger command, the slash commands are:
-
-| Command | Effect |
-| ------- | ------ |
-| `/project-name help` | Shows all available slash commands. |
-| `/project-name issue new <title> <shift+return> <description>` | Creates a new issue with title `<title>` and description `<description>`. |
-| `/project-name issue show <id>` | Shows the issue with ID `<id>`. |
-| `/project-name issue close <id>` | Closes the issue with ID `<id>`. |
-| `/project-name issue search <query>` | Shows up to 5 issues matching `<query>`. |
-| `/project-name issue move <id> to <project>` | Moves the issue with ID `<id>` to `<project>`. |
-| `/project-name issue comment <id> <shift+return> <comment>` | Adds a new comment with comment body `<comment>` to the issue with ID `<id>`. |
-| `/project-name deploy <from> to <to>` | [Deploys](#deploy-command) from the `<from>` environment to the `<to>` environment. |
-| `/project-name run <job name> <arguments>` | Executes the [ChatOps](../ci/chatops/index.md) job `<job name>` on the default branch. |
-
-## Issue commands
-
-You can create a new issue, display issue details, and search up to 5 issues.
-
-## Deploy command
-
-To deploy to an environment, GitLab tries to find a deployment
-manual action in the pipeline.
-
-If there's only one action for a given environment, it is triggered.
-If more than one action is defined, GitLab finds an action
-name that equals the environment name to deploy to.
-
-The command returns an error if no matching action is found.
+<!-- This redirect file can be deleted after 2023-09-19. -->
+<!-- Redirects that point to other docs in the same project expire in three months. -->
+<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
diff --git a/doc/operations/incident_management/slack.md b/doc/operations/incident_management/slack.md
index b007f253fd89e..aa0d057bfd854 100644
--- a/doc/operations/incident_management/slack.md
+++ b/doc/operations/incident_management/slack.md
@@ -37,7 +37,7 @@ Prerequisites:
 1. Authorize GitLab to take actions on behalf of your Slack user.
    Each user must do this before they can use any of the incident slash commands.
 
-   To start the authorization flow, try executing a non-incident [Slack slash command](../../integration/slash_commands.md),
+   To start the authorization flow, try executing a non-incident [Slack slash command](../../user/project/integrations/gitlab_slack_application.md#slash-commands),
    like `/gitlab <project-alias> issue show <id>`.
    The `<project-alias>` you select must be a project that has the GitLab for Slack app set up.
    For more information, see [issue 377548](https://gitlab.com/gitlab-org/gitlab/-/issues/377548).
diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md
index c357e16c96719..fd08c58cbcdaf 100644
--- a/doc/user/admin_area/moderate_users.md
+++ b/doc/user/admin_area/moderate_users.md
@@ -91,7 +91,7 @@ A blocked user:
 - Cannot sign in.
 - Cannot access Git repositories or the API.
 - Does not receive any notifications from GitLab.
-- Cannot use [slash commands](../../integration/slash_commands.md).
+- Cannot use [slash commands](../../user/project/integrations/gitlab_slack_application.md#slash-commands).
 - Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users).
 
 Personal projects, and group and user history of the blocked user are left intact.
@@ -149,7 +149,7 @@ A deactivated user:
 
 - Cannot access Git repositories or the API.
 - Does not receive any notifications from GitLab.
-- Cannot use [slash commands](../../integration/slash_commands.md).
+- Cannot use [slash commands](../../user/project/integrations/gitlab_slack_application.md#slash-commands).
 - Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users).
 
 Personal projects, and group and user history of the deactivated user are left intact.
diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md
index 8790c7213e515..77a08585e0832 100644
--- a/doc/user/project/integrations/gitlab_slack_application.md
+++ b/doc/user/project/integrations/gitlab_slack_application.md
@@ -52,43 +52,43 @@ you can also select **Reinstall GitLab for Slack app**.
 
 ## Slash commands
 
-After installing the GitLab for Slack app, everyone in your Slack workspace can use slash commands.
+You can use slash commands to run common GitLab operations. Replace `<project>` with a project full path.
 
-Replace `<project>` with the project full path, or create a shorter [project alias](#create-a-project-alias-for-slash-commands) for the slash commands.
+**For the GitLab for Slack app**:
 
-| Command | Effect |
-| ------- | ------ |
+- You must authorize your Slack user on GitLab.com when you run your first slash command.
+- You can [create a shorter project alias](#create-a-project-alias-for-slash-commands) for slash commands.
+
+**For [Slack slash commands](slack_slash_commands.md) on self-managed GitLab, [Mattermost slash commands](mattermost_slash_commands.md), and [ChatOps](../../../ci/chatops/index.md)**, do not add `gitlab` at the beginning of the command.
+
+The following slash commands are available:
+
+| Command | Description |
+| ------- | ----------- |
 | `/gitlab help` | Shows all available slash commands. |
-| `/gitlab <project> issue new <title> <shift+return> <description>` | Creates a new issue with the title `<title>` and description `<description>`. |
+| `/gitlab <project> issue new <title>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<description>` | Creates a new issue with the title `<title>` and description `<description>`. |
 | `/gitlab <project> issue show <id>` | Shows the issue with the ID `<id>`. |
 | `/gitlab <project> issue close <id>` | Closes the issue with the ID `<id>`. |
-| `/gitlab <project> issue search <query>` | Shows up to 5 issues matching `<query>`. |
+| `/gitlab <project> issue search <query>` | Shows up to five issues matching `<query>`. |
 | `/gitlab <project> issue move <id> to <project>` | Moves the issue with the ID `<id>` to `<project>`. |
-| `/gitlab <project> issue comment <id> <shift+return> <comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. |
+| `/gitlab <project> issue comment <id>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. |
 | `/gitlab <project> deploy <from> to <to>` | [Deploys](#the-deploy-slash-command) from the `<from>` environment to the `<to>` environment. |
 | `/gitlab <project> run <job name> <arguments>` | Executes the [ChatOps](../../../ci/chatops/index.md) job `<job name>` on the default branch. |
-| `/gitlab incident declare` | **Beta** Opens modal to [create a new incident](../../../operations/incident_management/slack.md). |
+| `/gitlab incident declare` | Opens a modal to [create a new incident from Slack](../../../operations/incident_management/slack.md) (Beta). |
 
-### The deploy slash command
+### The `deploy` slash command
 
-To deploy to an environment, GitLab tries to find a deployment
-manual action in the pipeline.
+To deploy to an environment, GitLab tries to find a deployment manual action in the pipeline.
 
-If there's only one action for a given environment, it is triggered.
-If more than one action is defined, GitLab finds an action
-name that matches the environment name to deploy to.
+If only one action is defined for a given environment, it is triggered.
+If more than one action is defined, GitLab tries to find an action name
+that matches the environment name to deploy to.
 
 The command returns an error if no matching action is found.
 
-### User authorization
-
-When you perform your first slash command, you must
-authorize your Slack user on GitLab.com.
-
 ### Create a project alias for slash commands
 
-By default, slash commands expect a project full path. To use a shorter alias
-instead:
+By default, slash commands expect a project full path. To create a shorter project alias in the GitLab for Slack app:
 
 1. Go to your project's home page.
 1. Go to **Settings > Integrations** (only visible on GitLab.com).
diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md
index a8d8323a651ce..6a09a1cfbcd38 100644
--- a/doc/user/project/integrations/mattermost_slash_commands.md
+++ b/doc/user/project/integrations/mattermost_slash_commands.md
@@ -6,12 +6,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Mattermost slash commands **(FREE)**
 
-You can use slash commands to run common GitLab operations, like creating an issue,
-from a [Mattermost](https://mattermost.com/) chat environment.
+You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations,
+like creating an issue, from a [Mattermost](https://mattermost.com/) chat environment.
 
 GitLab can also send events (such as `issue created`) to Mattermost as part of the
 separately configured [Mattermost notifications](mattermost.md).
 
+For a list of available slash commands, see [Slash commands](gitlab_slack_application.md#slash-commands).
+
 ## Configuration options
 
 GitLab provides different ways to configure Mattermost slash commands. For any of these options,
@@ -109,7 +111,7 @@ Your slash command can now communicate with your GitLab project.
 
 Prerequisite:
 
-- To run [slash commands](#available-slash-commands), you must have
+- To run [slash commands](gitlab_slack_application.md#slash-commands), you must have
   [permission](../../permissions.md#project-members-permissions) to
   perform the action in the GitLab project.
 
@@ -120,21 +122,10 @@ To interact with GitLab using Mattermost slash commands:
 
 You can see all authorized chat accounts in your Mattermost profile page under **Chat**.
 
-## Available slash commands
-
-The available slash commands for Mattermost are:
-
-| Command | Description | Example |
-| ------- | ----------- | ------- |
-| `/<trigger> issue new <title>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<description>` | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` |
-| `/<trigger> issue show <issue-number>` | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` |
-| `/<trigger> deploy <environment> to <environment>` | Start the CI/CD job that deploys from one environment to another (for example, `staging` to `production`). CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` |
-| `/<trigger> help` | View a list of available slash commands. | `/gitlab help` |
-
 ## Related topics
 
-- [Mattermost slash commands](https://developers.mattermost.com/integrate/slash-commands/)
-- [Linux package Mattermost](../../../integration/mattermost/index.md)
+- [Mattermost Linux package](../../../integration/mattermost/index.md)
+- [Slash commands at Mattermost](https://developers.mattermost.com/integrate/slash-commands/)
 
 ## Troubleshooting
 
diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md
index 74bd12561fb01..c1e04f2aa63c7 100644
--- a/doc/user/project/integrations/slack_slash_commands.md
+++ b/doc/user/project/integrations/slack_slash_commands.md
@@ -10,16 +10,18 @@ NOTE:
 This feature is only configurable on self-managed GitLab instances.
 For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead.
 
-If you want to control and view GitLab content while you're
-working in Slack, you can use Slack slash commands.
-To use Slack slash commands, you must configure both Slack and GitLab.
+You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations,
+like creating an issue, from a [Slack](https://slack.com/) chat environment.
+To use slash commands in Slack, you must configure both Slack and GitLab.
 
-GitLab can also send events (for example, `issue created`) to Slack as notifications.
-The [Slack notifications integration](slack.md) is configured separately.
+GitLab can also send events (such as `issue created`) to Slack as part of the
+separately configured [Slack notifications](slack.md).
 
-## Configure GitLab and Slack
+For a list of available slash commands, see [Slash commands](gitlab_slack_application.md#slash-commands).
 
-Slack slash command integrations are scoped to a project.
+## Configure the integration
+
+Slack slash commands are scoped to a project. To configure Slack slash commands:
 
 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project.
 1. Select **Settings > Integrations**.
@@ -35,7 +37,3 @@ Slack slash command integrations are scoped to a project.
 1. On the Slack configuration page, select **Save Integration** and copy the **Token**.
 1. Go back to the GitLab configuration page and paste in the **Token**.
 1. Ensure the **Active** checkbox is selected and select **Save changes**.
-
-## Slash commands
-
-You can now use the available [Slack slash commands](../../../integration/slash_commands.md).
-- 
GitLab