Revise documentation page, remove image

Before cross-linking to this page, I needed to clean up the
subheadings to bring them up to GitLab style standards. I rewrote
most of the page to get it up to our standards, and deleted an image
we really don't need.

app/helpers/services_helper.rb

@@ -4,29 +4,29 @@ module ServicesHelper
   def service_event_description(event)
     case event
     when "push", "push_events"
-      s_("ProjectService|Event will be triggered by a push to the repository")
+      s_("ProjectService|Event triggered when someone pushes to the repository.")
     when "tag_push", "tag_push_events"
-      s_("ProjectService|Event will be triggered when a new tag is pushed to the repository")
+      s_("ProjectService|Event triggered when a new tag is pushed to the repository.")
     when "note", "note_events"
-      s_("ProjectService|Event will be triggered when someone adds a comment")
+      s_("ProjectService|Event triggered when someone adds a comment.")
     when "confidential_note", "confidential_note_events"
-      s_("ProjectService|Event will be triggered when someone adds a comment on a confidential issue")
+      s_("ProjectService|Event triggered when someone adds a comment on a confidential issue.")
     when "issue", "issue_events"
-      s_("ProjectService|Event will be triggered when an issue is created/updated/closed")
+      s_("ProjectService|Event triggered when an issue is created, updated, or closed.")
     when "confidential_issue", "confidential_issue_events"
-      s_("ProjectService|Event will be triggered when a confidential issue is created/updated/closed")
+      s_("ProjectService|Event triggered when a confidential issue is created, updated, or closed.")
     when "merge_request", "merge_request_events"
-      s_("ProjectService|Event will be triggered when a merge request is created/updated/merged")
+      s_("ProjectService|Event triggered when a merge request is created, updated, or merged.")
     when "pipeline", "pipeline_events"
-      s_("ProjectService|Event will be triggered when a pipeline status changes")
+      s_("ProjectService|Event triggered when a pipeline status changes.")
     when "wiki_page", "wiki_page_events"
-      s_("ProjectService|Event will be triggered when a wiki page is created/updated")
+      s_("ProjectService|Event triggered when a wiki page is created or updated.")
     when "commit", "commit_events"
-      s_("ProjectService|Event will be triggered when a commit is created/updated")
+      s_("ProjectService|Event triggered when a commit is created or updated.")
     when "deployment"
-      s_("ProjectService|Event will be triggered when a deployment starts or finishes")
+      s_("ProjectService|Event triggered when a deployment starts or finishes.")
     when "alert"
-      s_("ProjectService|Event will be triggered when a new, unique alert is recorded")
+      s_("ProjectService|Event triggered when a new, unique alert is recorded.")
     end
   end
 

app/models/project_services/microsoft_teams_service.rb

@@ -2,7 +2,7 @@
 
 class MicrosoftTeamsService < ChatNotificationService
   def title
-    'Microsoft Teams Notification'
+    'Microsoft Teams notifications'
   end
 
   def description
@@ -14,13 +14,7 @@ class MicrosoftTeamsService < ChatNotificationService
   end
 
   def help
-    'This service sends notifications about projects events to Microsoft Teams channels.<br />
-    To set up this service:
-    <ol>
-      <li><a href="https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/connectors/connectors-using#setting-up-a-custom-incoming-webhook">Setup a custom Incoming Webhook using Office 365 Connectors For Microsoft Teams</a>.</li>
-      <li>Paste the <strong>Webhook URL</strong> into the field below.</li>
-      <li>Select events below to enable notifications.</li>
-    </ol>'
+    '<p>Use this service to send notifications about events in GitLab projects to your Microsoft Teams channels. <a href="https://docs.gitlab.com/ee/user/project/integrations/microsoft_teams.html">How do I configure this integration?</a></p>'
   end
 
   def webhook_placeholder
@@ -40,8 +34,8 @@ class MicrosoftTeamsService < ChatNotificationService
 
   def default_fields
     [
-      { type: 'text', name: 'webhook', placeholder: "e.g. #{webhook_placeholder}" },
-      { type: 'checkbox', name: 'notify_only_broken_pipelines' },
+      { type: 'text', name: 'webhook', placeholder: "#{webhook_placeholder}" },
+      { type: 'checkbox', name: 'notify_only_broken_pipelines', help: 'If selected, successful pipelines do not trigger a notification event.' },
       { type: 'select', name: 'branches_to_be_notified', choices: branch_choices }
     ]
   end

doc/user/project/integrations/microsoft_teams.md

@@ -6,49 +6,55 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Microsoft Teams service **(FREE)**
 
-## On Microsoft Teams
+You can integrate Microsoft Teams with GitLab, and display notifications about GitLab projects
+in Microsoft Teams. To integrate the services, you must:
 
-To enable Microsoft Teams integration you must create an incoming webhook integration on Microsoft
-Teams by following the steps below:
+1. [Configure Microsoft Teams](#configure-microsoft-teams) to enable a webhook
+   to listen for changes.
+1. [Configure your GitLab project](#configure-your-gitlab-project) to push notifications
+   to the Microsoft Teams webhook.
 
-1. Search for "incoming webhook" on the search bar in Microsoft Teams and select the
-   **Incoming Webhook** item.
+## Configure Microsoft Teams
+
+To configure Microsoft Teams to listen for notifications from GitLab:
+
+1. In Microsoft Teams, search for "incoming webhook" in the search bar, and select the
+   **Incoming Webhook** item:
 
    ![Select Incoming Webhook](img/microsoft_teams_select_incoming_webhook.png)
 
-1. Click the **Add to a team** button.
+1. Select **Add to a team**.
 1. Select the team and channel you want to add the integration to.
 1. Add a name for the webhook. The name is displayed next to every message that
    comes in through the webhook.
-1. Copy the webhook URL for the next steps.
-
-Learn more about
-[setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook).
-
-## On GitLab
-
-After you set up Microsoft Teams, it's time to set up GitLab.
-
-Navigate to the [Integrations page](overview.md#accessing-integrations)
-and select the **Microsoft Teams Notification** service to configure it.
-There, you see a checkbox with the following events that can be triggered:
-
-- Push
-- Issue
-- Confidential issue
-- Merge request
-- Note
-- Tag push
-- Pipeline
-- Wiki page
-
-At the end fill in your Microsoft Teams details:
-
-| Field | Description |
-| ----- | ----------- |
-| **Webhook** | The incoming webhook URL which you have to set up on Microsoft Teams. |
-| **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. |
-
-After you are all done, click **Save changes** for the changes to take effect.
-
-![Microsoft Teams configuration](img/microsoft_teams_configuration.png)
+1. Copy the webhook URL, as you need it to configure GitLab.
+
+## Configure your GitLab project
+
+After you configure Microsoft Teams to receive notifications, you must configure
+GitLab to send the notifications:
+
+1. Sign in to GitLab as a user with [Administrator](../../permissions.md) and go
+   to your project's page.
+1. Go to **Settings > Integrations** and select **Microsoft Teams Notification**.
+1. Select **Active** to enable the integration.
+1. Select the check box next to each **Trigger** to enable:
+   - Push
+   - Issue
+   - Confidential issue
+   - Merge request
+   - Note
+   - Confidential note
+   - Tag push
+   - Pipeline - If you enable this trigger, you can also select **Notify only broken pipelines** to be notified only about failed pipelines.
+   - Wiki page
+1. In **Webhook**, paste the URL you copied when you
+   [configured Microsoft Teams](#configure-microsoft-teams).
+1. (Optional) If you enabled the pipeline trigger, you can select the
+   **Notify only broken pipelines** check box to push notifications only when pipelines break.
+1. Select the branches you want to send notifications for.
+1. Click **Save changes**.
+
+## Resources
+
+- [Setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook).

locale/gitlab.pot

@@ -23984,40 +23984,40 @@ msgstr ""
 msgid "ProjectService|Enter new password"
 msgstr ""
 
-msgid "ProjectService|Event will be triggered by a push to the repository"
+msgid "ProjectService|Event triggered when a commit is created or updated."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when a commit is created/updated"
+msgid "ProjectService|Event triggered when a confidential issue is created, updated, or closed."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when a confidential issue is created/updated/closed"
+msgid "ProjectService|Event triggered when a deployment starts or finishes."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when a deployment starts or finishes"
+msgid "ProjectService|Event triggered when a merge request is created, updated, or merged."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when a merge request is created/updated/merged"
+msgid "ProjectService|Event triggered when a new tag is pushed to the repository."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when a new tag is pushed to the repository"
+msgid "ProjectService|Event triggered when a new, unique alert is recorded."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when a new, unique alert is recorded"
+msgid "ProjectService|Event triggered when a pipeline status changes."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when a pipeline status changes"
+msgid "ProjectService|Event triggered when a wiki page is created or updated."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when a wiki page is created/updated"
+msgid "ProjectService|Event triggered when an issue is created, updated, or closed."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when an issue is created/updated/closed"
+msgid "ProjectService|Event triggered when someone adds a comment on a confidential issue."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when someone adds a comment"
+msgid "ProjectService|Event triggered when someone adds a comment."
 msgstr ""
 
-msgid "ProjectService|Event will be triggered when someone adds a comment on a confidential issue"
+msgid "ProjectService|Event triggered when someone pushes to the repository."
 msgstr ""
 
 msgid "ProjectService|Issue URL"

spec/serializers/service_event_entity_spec.rb

@@ -17,7 +17,7 @@ RSpec.describe ServiceEventEntity do
       let(:event) { 'push' }
 
       it 'exposes correct attributes' do
-        expect(subject[:description]).to eq('Event will be triggered by a push to the repository')
+        expect(subject[:description]).to eq('Event triggered when someone pushes to the repository.')
         expect(subject[:name]).to eq('push_events')
         expect(subject[:title]).to eq('push')
         expect(subject[:value]).to be(true)
@@ -29,7 +29,7 @@ RSpec.describe ServiceEventEntity do
       let(:event) { 'note' }
 
       it 'exposes correct attributes' do
-        expect(subject[:description]).to eq('Event will be triggered when someone adds a comment')
+        expect(subject[:description]).to eq('Event triggered when someone adds a comment.')
         expect(subject[:name]).to eq('note_events')
         expect(subject[:title]).to eq('note')
         expect(subject[:value]).to eq(false)