Merge branch 'docs/slack-app' into 'master'

Refactor GitLab Slack app docs

Closes #2862

See merge request !2447

doc/user/project/integrations/gitlab_slack_application.md

-# Slack application (only available on GitLab.com)
+# GitLab Slack application
 
-Since GitLab 9.4 you can install GitLab.com Slack application to get [slash commands](https://docs.gitlab.com/ce/integration/slash_commands.html) working.
-The only difference is that all the commands should be prefixed with `/gitlab` keyword:
+>**Notes:**
+- Introduced in [GitLab Enterprise Edition] 9.4.
+- Currently only configurable for GitLab.com, it will not work for on-premises
+  installations. You can configure the [Slack slash commands](slack_slash_commands.md)
+  service instead. We're working with Slack on making this configurable for all
+  GitLab installations.
+
+Slack provides a native application which you can enable via your project's
+integrations on GitLab.com.
+
+## Configuration
+
+Keep in mind that you need to have the appropriate permissions for your Slack
+team in order to be able to install a new application, read more in Slack's
+docs on [Adding an app to your team][slack-docs].
+
+To enable GitLab's service for your Slack team:
+
+1. Go to your project's **Settings > Integration > Slack application** (only
+   visible on GitLab.com)
+1. Click the "Add to Slack" button
+
+That's all! You can now start using the Slack slash commands.
+
+## Usage
+
+After confirming the installation, you, and everyone else in your Slack team,
+can use all the [slash commands].
+
+When you perform your first slash command you will be asked to authorize your
+Slack user on GitLab.com.
+
+The only difference with the [manually configurable Slack slash commands][slack-manual]
+is that all the commands should be prefixed with the `/gitlab` keyword.
+We are working on making this configurable in the future.
+
+For example, to show the issue number `1001` under the `gitlab-org/gitlab-ce`
+project, you would do:
 
 ```
-# Show the issue #1001
 /gitlab gitlab-org/gitlab-ce issue show 1001
 ```
 
-To install GitLab application to your Slack team you need to go to
-`Project Settings > Integration > Slack application` page and press "Add to Slack" button.
-Keep in mind that you have to have appropriate permissions for that team to be able to
-install a new application, see details in [Add an app to your team](https://get.slack.help/hc/en-us/articles/202035138-Adding-apps-to-your-team).
-After confirming installation you, and everyone else in your Slack team, can use all the commands.
-When you perform your first slash command you will be asked to authorize your Slack user
-inside GitLab.com.
+[slack-docs]: https://get.slack.help/hc/en-us/articles/202035138-Adding-apps-to-your-team
+[slash commands]: ../../../integration/slash_commands.md
+[slack-manual]: slack_slash_commands.md

doc/user/project/integrations/project_services.md

@@ -46,6 +46,7 @@ Click on the service links to see further configuration instructions and details
 | Pipelines emails | Email the pipeline status to a list of recipients |
 | [Slack Notifications](slack.md) | Send GitLab events (e.g. issue created) to Slack as notifications |
 | [Slack slash commands](slack_slash_commands.md) | Use slash commands in Slack to control GitLab |
+| [GitLab Slack application](gitlab_slack_application.md) | Use Slack's official application 
 | PivotalTracker | Project Management Software (Source Commits Endpoint) |
 | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps |
 | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop |