Restructure steps for MM slash commands service

[ci skip]

1 files changed, 61 insertions, 34 deletions

diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md
index 36b72de1be0..1507dfa3abd 100644
--- a/doc/project_services/mattermost_slash_commands.md
+++ b/doc/project_services/mattermost_slash_commands.md
@@ -12,7 +12,7 @@ Mattermost 3.4 and up is required.
 
 If you have the Omnibus GitLab package installed, Mattermost is already bundled
 in it. All you have to do is configure it. Read more in the
-[Omnibus GitLab Mattermost documentation][omnimatdocs].
+[Omnibus GitLab Mattermost documentation][omnimmdocs].
 
 ## Configuration
 
@@ -22,7 +22,7 @@ commands in Mattermost and then enable the service in GitLab.
 
 ### Step 1. Enable custom slash commands in Mattermost
 
-The first thing to do in Mattermost is to enable the custom slash commands from
+The first thing to do in Mattermost is to enable custom slash commands from
 the administrator console.
 
 1. Log in with an account that has admin privileges and navigate to the system
@@ -41,50 +41,74 @@ the administrator console.
 
 1. Click **Save** at the bottom to save the changes.
 
-### Step 2. Create a new custom command in Mattermost
+### Step 2. Open the Mattermost slash commands service in GitLab
 
-Now that you have enabled the custom slash commands:
+1. Open a new tab for GitLab and go to your project's settings
+   **Services ➔ Mattermost command**. A screen will appear with all the values you
+   need to copy in Mattermost as described in the next step. Leave the window open.
 
-1. Back to your team page settings, you should see the **Integrations** option.
+    >**Note:**
+    GitLab will propose some values for the Mattermost settings. The only one
+    required to copy-paste as-is is the **Request URL**, all the others are just
+    suggestions.
+
+    ![Mattermost setup instructions](img/mattermost_config_help.png)
+
+    ---
+
+1. Proceed to the next step and create a slash command in Mattermost with the
+   above values.
+
+### Step 3. Create a new custom slash command in Mattermost
+
+Now that you have enabled the custom slash commands in Mattermost and opened
+the Mattermost slash commands service in GitLab, it's time to copy these values
+in a new slash command.
+
+1. Back to Mattermost, under your team page settings, you should see the
+   **Integrations** option.
 
     ![Mattermost team integrations](img/mattermost_team_integrations.png)
 
     ---
 
-1. Go to the **Slash Command** integration and add a new one by clicking the
+1. Go to the **Slash Commands** integration and add a new one by clicking the
    **Add Slash Command** button.
 
     ![Mattermost add command](img/mattermost_add_slash_command.png)
 
     ---
 
-1. Fill in the options for the custom command.
+1. Fill in the options for the custom command as described in
+   [step 2](#step-2-open-the-mattermost-slash-commands-service-in-gitlab).
 
-    ![Mattermost add command configuration](img/mattermost_slash_command_configuration.png)
+    >**Note:**
+    If you plan on connecting multiple projects, pick a slash command trigger
+    word that relates to your projects such as `/gitlab-project-name` or even
+    just `/project-name`. Only use `/gitlab` if you will only connect a single
+    project to your Mattermost team.
 
-    > **Note:**
-    When configuring the GitLab Mattermost command service in the next step,
-    you will be presented with some predefined values to paste into the
-    Mattermost slash command settings.
+    ![Mattermost add command configuration](img/mattermost_slash_command_configuration.png)
 
 1. After you setup all the values, copy the token (we will use it below) and
    click **Done**.
 
->
-[**➔ Read more on Mattermost slash commands**][mmslashdocs].
+    ![Mattermost slash command token](img/mattermost_slash_command_token.png)
 
-### Step 3. Configure GitLab
+### Step 4. Copy the Mattermost token into the Mattermost slash command service
 
-1. Go to your project's settings **Services ➔ Mattermost command**. A screen
-   will appear with all the values you can copy to the Mattermost page in the
-   previous step.
+1. In GitLab, paste the Mattermost token you copied in the previous step and
+   check the **Active** checkbox.
 
-    ![Mattermost setup instructions](img/mattermost_config_help.png)
+    ![Mattermost copy token to GitLab](img/mattermost_gitlab_token.png)
 
-1. Paste the Mattermost token you copied when setting up the Mattermost slash
-   command and check the **Active** checkbox.
 1. Click **Save changes** for the changes to take effect.
 
+---
+
+You are now set to start using slash commands in Mattermost that talk to the
+GitLab project you configured.
+
 ## Authorizing Mattermost to interact with GitLab
 
 The first time a user will interact with the newly created slash commands,
@@ -92,7 +116,7 @@ Mattermost will trigger an authorization process.
 
 ![Mattermost bot authorize](img/mattermost_bot_auth.png)
 
-This will connect connect your Mattermost user with your GitLab user. You can
+This will connect your Mattermost user with your GitLab user. You can
 see all authorized chat accounts in your profile's page under **Chat**.
 
 When the authorization process is complete, you can start interacting with
@@ -102,18 +126,14 @@ GitLab using the Mattermost commands.
 
 The available slash commands so far are:
 
-- `/<trigger> issue create <title>\n<description>` - Create a new issue to the
-  project that `<trigger>` is tied to.
-- `/<trigger> issue show <issue-number>` - Show the issue with ID `<issue-number>`
-  from the project that `<trigger>` is tied to.
-- `/<trigger> deploy <environment> to <environment>` - Start the CI job that
-  deploys from an environment to another, for example `staging` to `production`.
-  CI must be properly configured.
+| Command | Description | Example |
+| ------- | ----------- | ------- |
+| `/<trigger> issue create <title>\n<description>` | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/trigger issue create 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. | `/trigger issue show 42` |
+| `/<trigger> deploy <environment> to <environment>` | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured][ciyaml]. | `/trigger deploy staging to production` |
 
-If you enabled autocomplete when you created the Mattermost command, you can
-use the autocomplete hint to see the available commands that can interact
-with GitLab. If for example the autocomplete hint was set to `help` and the
-command trigger word to `my-project`, then to see all available command type:
+To see a list of available commands that can interact with GitLab, type the
+trigger word followed by `help`:
 
 ```
 /my-project help
@@ -126,5 +146,12 @@ command trigger word to `my-project`, then to see all available command type:
 The permissions to run the [available commands](#available-commands) derive from
 the [permissions you have on the project](../user/permissions.md#project).
 
-[omnimatdocs]: https://docs.gitlab.com/omnibus/gitlab-mattermost/
+## Further reading
+
+- [Mattermost slash commands documentation][mmslashdocs]
+- [Omnibus GitLab Mattermost][omnimmdocs]
+
+
+[omnimmdocs]: https://docs.gitlab.com/omnibus/gitlab-mattermost/
 [mmslashdocs]: https://docs.mattermost.com/developer/slash-commands.html
+[ciyaml]: ../ci/yaml/README.md