Add latest changes from gitlab-org/gitlab@master

4 files changed, 42 insertions, 38 deletions

diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md
index 299b1e53ff2..2366005ca55 100644
--- a/doc/integration/facebook.md
+++ b/doc/integration/facebook.md
@@ -6,65 +6,69 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Use Facebook as an OAuth 2.0 authentication provider **(FREE ALL)**
 
-To enable the Facebook OmniAuth provider you must register your application with
-Facebook. Facebook generates an app ID and secret key for you to use.
+You can use the Facebook OmniAuth provider to authenticate users with their Facebook account.
 
-1. Sign in to the [Facebook Developer Platform](https://developers.facebook.com/).
+To enable the Facebook OmniAuth provider, you must:
 
-1. Choose "My Apps" > "Add a New App"
+- Register your application with Facebook. Facebook generates an app ID and a secret key for you to use.
+- Configure the GitLab server.
 
-1. Select the type "Website"
+## Register your application with Facebook
 
-1. Enter a name for your app. This can be anything. Consider something like
-   "<Organization>'s GitLab" or "<Your Name>'s GitLab" or something
-   else descriptive.
+1. Sign in to your [Facebook developer account](https://developers.facebook.com/).
 
-1. Choose "Create New Facebook App ID"
+1. Go to **My Apps** > **Create App**, then complete the following steps:
 
-1. Select a Category, for example "Productivity"
+   1. Enter a descriptive name for your app. For example: **`<your_organization's>` GitLab** or **`<your_name's>` GitLab**.
 
-1. Choose "Create App ID"
+   1. Select **Create New Facebook App ID**.
 
-1. Enter the address of your GitLab installation at the bottom of the package
+   1. Select a **Category**. For example **Productivity**.
 
-   ![Facebook Website URL](img/facebook_website_url.png)
+   1. Select **Create App ID**.
 
-1. Choose "Next"
+   1. At the bottom of the page, enter the address of your GitLab installation.
+
+      ![Facebook Website URL](img/facebook_website_url.png)
+
+   1. Select **Next**.
 
 1. In the upper-right corner, select **Skip Quick Start**.
 
-1. Choose "Settings" in the menu on the left
+1. From the menu on the left, select **Settings**, then complete the following:
 
-1. Fill in a contact email for your app
+   1. Enter a contact email for your app.
 
-   ![Facebook App Settings](img/facebook_app_settings.png)
+      ![Facebook App Settings](img/facebook_app_settings.png)
 
-1. Choose "Save Changes"
+   1. Select **Save Changes**.
 
-1. Choose "Status & Review" in the menu on the left
+1. From the menu on the left, select **Status & Review**, then complete the following:
 
-1. Change the switch on the right from No to Yes
+   1. Change the switch on the right from **No** to **Yes**.
 
-1. Choose "Confirm" when prompted to make the app public
+   1. When prompted to make the app public, select **Confirm**.
 
-1. Choose "Dashboard" in the menu on the left
+1. From the menu on the left, select **Dashboard**, then complete the following:
 
-1. Choose "Show" next to the hidden "App Secret"
+   1. Next to the hidden **App Secret**, select **Show**.
 
-1. You should now see an app key and app secret (see screenshot). Keep this page
-   open as you continue configuration.
+   1. Copy the **App ID** and **App Secret**. Keep this page
+      open as you continue configuration.
 
-   ![Facebook API Keys](img/facebook_api_keys.png)
+      ![Facebook API Keys](img/facebook_api_keys.png)
 
-1. On your GitLab server, open the configuration file.
+## Configure the GitLab server
 
-   For Linux package installations:
+1. On your GitLab server, open the configuration file:
+
+   - For Linux package installations:
 
    ```shell
    sudo editor /etc/gitlab/gitlab.rb
    ```
 
-   For self-compiled installations:
+   - For self-compiled installations:
 
    ```shell
    cd /home/git/gitlab
@@ -76,9 +80,9 @@ Facebook. Facebook generates an app ID and secret key for you to use.
    to add `facebook` as a single sign-on provider. This enables Just-In-Time
    account provisioning for users who do not have an existing GitLab account.
 
-1. Add the provider configuration.
+1. Add the provider configuration:
 
-   For Linux package installations:
+   - For Linux package installations:
 
    ```ruby
    gitlab_rails['omniauth_providers'] = [
@@ -91,7 +95,7 @@ Facebook. Facebook generates an app ID and secret key for you to use.
    ]
    ```
 
-   For self-compiled installations:
+   - For self-compiled installations:
 
    ```yaml
    - { name: 'facebook',
@@ -100,9 +104,11 @@ Facebook. Facebook generates an app ID and secret key for you to use.
        app_secret: 'YOUR_APP_SECRET' }
    ```
 
-1. Change 'YOUR_APP_ID' to the API key from Facebook page in step 10.
+1. In the provide configuration, paste the following values:
+
+   1. `YOUR_APP_ID`: The **App ID** you copied in the previous step.
 
-1. Change 'YOUR_APP_SECRET' to the API secret from the Facebook page in step 10.
+   1. `YOUR_APP_SECRET`: The **App Secret** you copied in the previous step.
 
 1. Save the configuration file.
 
@@ -110,7 +116,5 @@ Facebook. Facebook generates an app ID and secret key for you to use.
    - If you installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation).
    - If you self-compiled your installation, [restart GitLab](../administration/restart_gitlab.md#self-compiled-installations).
 
-On the sign in page there should now be a Facebook icon below the regular sign
-in form. Select the icon to begin the authentication process. Facebook asks the
-user to sign in and authorize the GitLab application. If everything goes well
-the user is returned to GitLab and signed in.
+On the sign in page, a Facebook icon should now appear below the sign-in fields.
+The user can select the icon to sign in.
diff --git a/doc/integration/img/facebook_api_keys.png b/doc/integration/img/facebook_api_keys.png
index 7480b144091..fa16ff2c803 100644
--- a/doc/integration/img/facebook_api_keys.png
+++ b/doc/integration/img/facebook_api_keys.png
diff --git a/doc/integration/img/facebook_app_settings.png b/doc/integration/img/facebook_app_settings.png
index 81f38cab16e..b2ff3066051 100644
--- a/doc/integration/img/facebook_app_settings.png
+++ b/doc/integration/img/facebook_app_settings.png
diff --git a/doc/integration/img/facebook_website_url.png b/doc/integration/img/facebook_website_url.png
index 7873c9905f1..56023a9a003 100644
--- a/doc/integration/img/facebook_website_url.png
+++ b/doc/integration/img/facebook_website_url.png