Merge branch 'docs-ssot-customization' into 'master'

SSoT for customization docs

Closes #64588

See merge request gitlab-org/gitlab-ce!31308

7 files changed, 192 insertions, 66 deletions

diff --git a/doc/customization/branded_login_page.md b/doc/customization/branded_login_page.md
index b892f59d777..afcc2b71284 100644
--- a/doc/customization/branded_login_page.md
+++ b/doc/customization/branded_login_page.md
@@ -1,19 +1,38 @@
-# Changing the appearance of the login page
+---
+type: howto
+---
 
-GitLab offers a way to put your company's identity on the login page of your GitLab server and make it a branded login page.
+# Changing the logo and description on the login page
 
-By default, the page shows the GitLab logo and description.
+You can customize the login page of your GitLab server to show the logo and
+description of your organization.
+
+By default, the page shows the GitLab logo and description:
 
 ![default_login_page](branded_login_page/default_login_page.png)
 
-## Changing the appearance of the login page
+To customize the login page:
 
-Navigate to the **Admin** area and go to the **Appearance** page.
+1. Navigate to the **Admin** area and go to the **Appearance** page.
+1. Fill in your desired Title and Description. You can also choose an image file
+   of the logo for your organization.
 
-Fill in the required details like Title, Description and upload the company logo.
+   ![appearance](branded_login_page/appearance.png)
 
-![appearance](branded_login_page/appearance.png)
+1. Save your changes.
 
-After saving the page, your GitLab login page will have the details you filled in:
+Your GitLab login page will display the details you provided:
 
 ![company_login_page](branded_login_page/custom_sign_in.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/branded_page_and_email_header.md b/doc/customization/branded_page_and_email_header.md
index 9a0f0b382fa..370c1461d30 100644
--- a/doc/customization/branded_page_and_email_header.md
+++ b/doc/customization/branded_page_and_email_header.md
@@ -1,15 +1,37 @@
-# Changing the logo on the overall page and email header
+---
+type: howto
+---
 
-Navigate to the **Admin** area and go to the **Appearance** page.
+# Changing the navigation bar and email header logo
 
-Upload the custom logo (**Header logo**) in the section **Navigation bar**.
+You can customize the logo that appears in email headers and in the navigation
+bar on pages that are displayed by your GitLab server.
 
-![appearance](branded_page_and_email_header/appearance.png)
+1. Navigate to the **Admin** area and go to the **Appearance** page, then locate
+   the **Navigation bar** section.
+1. For the **Header Logo**, choose an image file of the logo for your
+   organization.
 
-After saving the page, your GitLab navigation bar will contain the custom logo:
+   ![appearance](branded_page_and_email_header/appearance.png)
+
+1. Save your changes.
+
+Your GitLab navigation bar will display the custom logo:
 
 ![custom_brand_header](branded_page_and_email_header/custom_brand_header.png)
 
-The GitLab pipeline emails will also have the custom logo:
+The GitLab pipeline emails will also display the custom logo:
 
 ![custom_email_header](branded_page_and_email_header/custom_email_header.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/favicon.md b/doc/customization/favicon.md
index 45a18159b5e..dbde6e8c03b 100644
--- a/doc/customization/favicon.md
+++ b/doc/customization/favicon.md
@@ -1,16 +1,37 @@
+---
+type: howto
+---
+
 # Changing the favicon
 
 > [Introduced][ce-14497] in GitLab 11.0.
 
 [ce-14497]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14497
 
-Navigate to the **Admin** area and go to the **Appearance** page.
+You can customize the favicon (the icon displayed in your web browser's
+address bar and web page tabs) for your GitLab server.
+
+1. Navigate to the **Admin** area and go to the **Appearance** page, then
+   locate the **Favicon** section.
+1. Upload an image file of your favicon.
 
-Upload the custom favicon (**Favicon**) in the section **Favicon**.
+   ![appearance](favicon/appearance.png)
 
-![appearance](favicon/appearance.png)
+1. Save your changes.
 
-After saving the page, the new favicon will be shown in the browser. The main
-favicon as well as the CI status icons will show the custom icon:
+Your new favicon will display in the browser. The main favicon and the CI
+status icons will show the custom icon:
 
 ![custom_favicon](favicon/custom_favicon.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/help_message.md b/doc/customization/help_message.md
index c2e592d03bf..a4d8f295750 100644
--- a/doc/customization/help_message.md
+++ b/doc/customization/help_message.md
@@ -1,13 +1,36 @@
-# GitLab Help custom text
+---
+type: howto
+---
 
-In larger organizations it is useful to have information about who has the responsibility of maintaining the company GitLab server.
+# Customizing the 'Help' and login page messages
 
-1. Navigate to the admin area, click on **Preferences** and expand **Help page**.
+In large organizations, it is useful to have information about who maintains
+the company GitLab server. You can customize and display this information on
+the GitLab login page and on the GitLab server's `/help` page.
 
-1. Under **Help text** fill in the required information about the person(s) administering GitLab or any other information relevant to your needs.
+1. Navigate to the **Admin** area, then click on **Preferences** and expand
+   **Help page**.
+1. Under **Help page text**, fill in the required information about the
+   person(s) administering GitLab. This text can also contain any other
+   information that you wish to display to users.
 
-    ![help message](help_message/help_text.png)
+   ![help message](help_message/help_text.png)
 
-1. After saving the page this information will be shown on the GitLab login page and on the GitLab `/help` page (e.g., <https://gitlab.com/help>).
+1. Save your changes.
 
-    ![help text on help page](help_message/help_text_on_help_page.png)
+The information you entered will be shown on the GitLab login page and on the
+GitLab `/help` page (e.g., <https://gitlab.com/help>).
+
+![help text on help page](help_message/help_text_on_help_page.png)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/index.md b/doc/customization/index.md
index 0198059297f..f17a2d80e2c 100644
--- a/doc/customization/index.md
+++ b/doc/customization/index.md
@@ -1,18 +1,18 @@
 ---
+type: index
 description: Learn how to customize GitLab's appearance for self-managed installations.
 ---
 
 # Customizing GitLab's appearance **(CORE ONLY)**
 
-For GitLab self-managed instances, it's possible to customize
-a few pages.
+For GitLab self-managed instances, you can customize the page logo,
+email headers, favicon, and several other aspects of GitLab's appearance.
 
-Read through the following documents to adjust GitLab's
-look and feel to meet your needs:
+The following pages explain how to customize the appearance of your instance:
 
-- [Custom login page](branded_login_page.md)
-- [Custom header and email logo](branded_page_and_email_header.md)
-- [Custom favicon](favicon.md)
-- [Libravatar](libravatar.md)
-- [New project page](new_project_page.md)
-- [Custom `/help` message](help_message.md)
\ No newline at end of file
+- [Changing the logo and description on the login page](branded_login_page.md)
+- [Changing the navigation bar and email header logo](branded_page_and_email_header.md)
+- [Changing the favicon](favicon.md)
+- [Customizing the new project page](new_project_page.md)
+- [Customizing the `/help` and login page messages](help_message.md)
+- [Using the Libravatar service with GitLab](libravatar.md)
diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md
index e618f3be2fe..1c3bf877fa1 100644
--- a/doc/customization/libravatar.md
+++ b/doc/customization/libravatar.md
@@ -1,14 +1,20 @@
-# Use Libravatar service with GitLab
+---
+type: howto
+---
 
-GitLab by default supports [Gravatar](https://gravatar.com) avatar service.
-Libravatar is a service which delivers your avatar (profile picture) to other websites and their API is
-[heavily based on gravatar](https://wiki.libravatar.org/api/).
+# Using the Libravatar service with GitLab
 
-This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server.
+GitLab by default supports the [Gravatar](https://gravatar.com) avatar service.
+
+Libravatar is another service that delivers your avatar (profile picture) to
+other websites. The Libravatar API is
+[heavily based on gravatar](https://wiki.libravatar.org/api/), so you can
+easily switch to the Libravatar avatar service or even a self-hosted Libravatar
+server.
 
 ## Configuration
 
-In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set
+In the [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set
 the configuration options as follows:
 
 ### For HTTP
@@ -29,12 +35,14 @@ the configuration options as follows:
     ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
 ```
 
-### Self-hosted
+### Self-hosted Libravatar server
 
-If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration
-but the important part is to provide the same placeholders so GitLab can parse the URL correctly.
+If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/),
+the URL will be different in the configuration, but you must provide the same
+placeholders so GitLab can parse the URL correctly.
 
-For example, you host a service on `http://libravatar.example.com` the `plain_url` you need to supply in `gitlab.yml` is
+For example, you host a service on `http://libravatar.example.com` and the
+`plain_url` you need to supply in `gitlab.yml` is
 
 `http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon`
 
@@ -42,37 +50,52 @@ For example, you host a service on `http://libravatar.example.com` the `plain_ur
 
 In `/etc/gitlab/gitlab.rb`:
 
-#### For http
+#### For HTTP
 
 ```ruby
 gitlab_rails['gravatar_enabled'] = true
 gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
 ```
 
-#### For https
+#### For HTTPS
 
 ```ruby
 gitlab_rails['gravatar_enabled'] = true
 gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
 ```
 
-Run `sudo gitlab-ctl reconfigure` for changes to take effect.
+Then run `sudo gitlab-ctl reconfigure` for the changes to take effect.
 
 ## Default URL for missing images
 
-[Libravatar supports different sets](https://wiki.libravatar.org/api/) of `missing images` for emails not found on the Libravatar service.
-
-In order to use a different set other than `identicon`, replace `&d=identicon` portion of the URL with another supported set.
-For example, you can use `retro` set in which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"`
+[Libravatar supports different sets](https://wiki.libravatar.org/api/) of
+missing images for user email addresses that are not found on the Libravatar
+service.
 
-## Usage examples
+In order to use a set other than `identicon`, replace the `&d=identicon`
+portion of the URL with another supported set.
+For example, you can use the `retro` set, in which case the URL would look like:
+`plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"`
 
-### For Microsoft Office 365
+## Usage examples for Microsoft Office 365
 
-If your users are Office 365-users, the "GetPersonaPhoto" service can be used. Note that this service requires login, so this use case is
-most useful in a corporate installation, where all users have access to Office 365.
+If your users are Office 365 users, the `GetPersonaPhoto` service can be used.
+Note that this service requires a login, so this use case is most useful in a
+corporate installation where all users have access to Office 365.
 
 ```ruby
 gitlab_rails['gravatar_plain_url'] = 'http://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120'
 gitlab_rails['gravatar_ssl_url'] = 'https://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120'
 ```
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/customization/new_project_page.md b/doc/customization/new_project_page.md
index 148bf9512c6..43b95a76d08 100644
--- a/doc/customization/new_project_page.md
+++ b/doc/customization/new_project_page.md
@@ -1,20 +1,38 @@
+---
+type: howto
+---
+
 # Customizing the new project page
 
-It is possible to add a markdown-formatted message to your GitLab
-new project page.
+You can add a markdown-formatted message to your GitLab new project page.
 
 By default, the new project page shows a sidebar with general information:
 
-![](new_project_page/default_new_project_page.png)
+![default_new_project_page](new_project_page/default_new_project_page.png)
+
+To customize the information in the sidebar:
+
+1. Navigate to the **Admin** area and go to the **Appearance** page, then
+   locate the **New project pages** section.
+1. Fill in your new project project guidelines:
+
+   ![appearance_settings](new_project_page/appearance_settings.png)
 
-## Changing the appearance of the new project page
+1. Save the page.
 
-Navigate to the **Admin** area and go to the **Appearance** page.
+Your new project page will show the customized guidelines in the sidebar, below
+the general information:
 
-Fill in your project guidelines:
+![custom_new_project_page](new_project_page/custom_new_project_page.png)
 
-![](new_project_page/appearance_settings.png)
+<!-- ## Troubleshooting
 
-After saving the page, your new project page will show the guidelines in the sidebar, below the general information:
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
 
-![](new_project_page/custom_new_project_page.png)
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->