Refine topics for Phase 2 of SSoT auditdocs/ssot-phase-two

Includes admin_area and application_security
topics.

10 files changed, 187 insertions, 24 deletions

diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md
index 8088c33fc9c..0c5d2f81e25 100644
--- a/doc/user/admin_area/abuse_reports.md
+++ b/doc/user/admin_area/abuse_reports.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Abuse reports
 
 View and resolve abuse reports from GitLab users.
@@ -59,3 +63,15 @@ page:
 NOTE: **Note:**
 Users can be [blocked](../../api/users.md#block-user) and
 [unblocked](../../api/users.md#unblock-user) using the GitLab API.
+
+<!-- ## 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/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md
index 02445abdb37..01b6558bdbe 100644
--- a/doc/user/admin_area/broadcast_messages.md
+++ b/doc/user/admin_area/broadcast_messages.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Broadcast Messages
 
 GitLab can display messages to all users of a GitLab instance in a banner that appears in the UI.
@@ -51,3 +55,15 @@ Once deleted, the broadcast message is removed from the list of broadcast messag
 
 NOTE: **Note:**
 Broadcast messages can be deleted while active.
+
+<!-- ## 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/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md
index 427f3103cfc..02c2efaa4f3 100644
--- a/doc/user/admin_area/custom_project_templates.md
+++ b/doc/user/admin_area/custom_project_templates.md
@@ -1,26 +1,49 @@
+---
+type: reference
+---
+
 # Custom instance-level project templates **(PREMIUM ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2.
 
-When you create a new [project](../project/index.md), creating it based on custom project templates is
-a convenient bootstrap option.
+GitLab administrators can configure the group where all the custom project
+templates are sourced.
 
-GitLab administrators can configure a GitLab group that serves as template
-source for an entire GitLab instance under **Admin area > Settings > Custom project templates**.
+Every project directly under the group namespace will be
+available to the user if they have access to them. For example:
+
+- Public project in the group will be available to every logged in user.
+- Private projects will be available only if the user is a member of the project.
+
+Repository and database information that are copied over to each new project are
+identical to the data exported with
+[GitLab's Project Import/Export](../project/settings/import_export.md).
 
 NOTE: **Note:**
 To set project templates at a group level,
 see [Custom group-level project templates](../group/custom_project_templates.md).
 
-Within this section, you can configure the group where all the custom project
-templates are sourced. Every project directly under the group namespace will be
-available to the user if they have access to them. For example, every public
-project in the group will be available to every logged in user.
+## Configuring
 
-However, private projects will be available only if the user is a member of the project.
+GitLab administrators can configure a GitLab group that serves as template
+source for an entire GitLab instance by:
+
+1. Navigating to **Admin area > Settings > Templates**.
+1. Expanding **Custom project templates**.
+1. Selecting a group to use.
+1. Pressing **Save changes**.
 
 NOTE: **Note:**
 Projects below subgroups of the template group are **not** supported.
 
-Repository and database information that are copied over to each new project are
-identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md).
+<!-- ## 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/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md
index da75684a3fe..86491c7d74e 100644
--- a/doc/user/application_security/container_scanning/index.md
+++ b/doc/user/application_security/container_scanning/index.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Container Scanning **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672)
@@ -47,7 +51,7 @@ To enable Container Scanning in your pipeline, you need:
   your Docker image to your project's [Container Registry](../../project/container_registry.md).
   The name of the Docker image should match the following scheme:
 
-  ```
+  ```text
   $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA
   ```
 
@@ -114,7 +118,7 @@ When the GitLab Runner uses the Docker executor and NFS is used
 (e.g., `/var/lib/docker` is on an NFS mount), Container Scanning might fail with
 an error like the following:
 
-```
+```text
 docker: Error response from daemon: failed to copy xattrs: failed to set xattr "security.selinux" on /path/to/file: operation not supported.
 ```
 
diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md
index 4b98dd73d76..88e2d1ef22b 100644
--- a/doc/user/application_security/dast/index.md
+++ b/doc/user/application_security/dast/index.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Dynamic Application Security Testing (DAST) **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4348)
@@ -199,3 +203,15 @@ Once a vulnerability is found, you can interact with it. Read more on how to
 
 For more information about the vulnerabilities database update, check the
 [maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).
+
+<!-- ## 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/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md
index a2f0584e8dc..6a810757a28 100644
--- a/doc/user/application_security/dependency_scanning/index.md
+++ b/doc/user/application_security/dependency_scanning/index.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Dependency Scanning **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105)
@@ -150,7 +154,7 @@ using environment variables.
 | `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT`  | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. |
 | `DS_PULL_ANALYZER_IMAGE_TIMEOUT`        | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. |
 | `DS_RUN_ANALYZER_TIMEOUT`               | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. |
-| `PIP_INDEX_URL`                         | Base URL of Python Package Index (default https://pypi.org/simple). |
+| `PIP_INDEX_URL`                         | Base URL of Python Package Index (default `https://pypi.org/simple`). |
 | `PIP_EXTRA_INDEX_URL`                   | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma separated. |
 
 ## Reports JSON format
@@ -342,3 +346,15 @@ Please check the [Release Process documentation](https://gitlab.com/gitlab-org/s
 You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project
 to find a vulnerability in the Gemnasium database.
 You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md).
+
+<!-- ## 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/user/application_security/index.md b/doc/user/application_security/index.md
index 56a4cbd26d2..31f0b5a050c 100644
--- a/doc/user/application_security/index.md
+++ b/doc/user/application_security/index.md
@@ -1,10 +1,22 @@
+---
+type: reference, howto
+---
+
 # GitLab Secure **(ULTIMATE)**
 
-Check your application for security vulnerabilities that may lead to unauthorized access,
-data leaks, and denial of services. GitLab will perform static and dynamic tests on the
-code of your application, looking for known flaws and report them in the merge request
-so you can fix them before merging. Security teams can use dashboards to get a
-high-level view on projects and groups, and start remediation processes when needed.
+Check your application for security vulnerabilities that may lead to
+unauthorized access, data leaks, and denial of services.
+
+GitLab will perform static and dynamic tests on the code of your application,
+looking for known flaws and report them in the merge request so you can fix
+them before merging.
+
+Security teams can use dashboards to get a high-level view on projects and
+groups, and start remediation processes when needed.
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview of application security with GitLab, see
+[Security Deep Dive](https://www.youtube.com/watch?v=k4vEJnGYy84).
 
 ## Security scanning tools
 
@@ -54,7 +66,7 @@ Each security vulnerability in the merge request report or the
 entry, a detailed information will pop up with different possible options:
 
 - [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability
-  will place a <s>strikethrough</s> styling on it.
+  will place a ~~strikethrough~~ styling on it.
 - [Create issue](#creating-an-issue-for-a-vulnerability): The new issue will
   have the title and description pre-populated with the information from the
   vulnerability report and will be created as [confidential](../project/issues/confidential_issues.md) by default.
@@ -124,7 +136,7 @@ generated by GitLab. To apply the fix:
 #### Creating a merge request from a vulnerability
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9224) in
-  [GitLab Ultimate](https://about.gitlab.com/pricing) 11.9.
+> [GitLab Ultimate](https://about.gitlab.com/pricing) 11.9.
 
 In certain cases, GitLab will allow you to create a merge request that will
 automatically remediate the vulnerability. Any vulnerability that has a
@@ -135,3 +147,15 @@ If this action is available there will be a **Create merge request** button in t
 Clicking on this button will create a merge request to apply the solution onto the source branch.
 
 ![Create merge request from vulnerability](img/create_issue_with_list_hover.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/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md
index b0eb753938b..c324848c703 100644
--- a/doc/user/application_security/license_management/index.md
+++ b/doc/user/application_security/license_management/index.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # License Management **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483)
@@ -227,3 +231,15 @@ pipeline ID that has a `license_management` job to see the Licenses tab with the
 licenses (if any).
 
 ![License Management Pipeline Tab](img/license_management_pipeline_tab.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/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md
index 7df86eedd18..aac881112ff 100644
--- a/doc/user/application_security/sast/index.md
+++ b/doc/user/application_security/sast/index.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Static Application Security Testing (SAST) **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3775)
@@ -334,3 +338,15 @@ Once a vulnerability is found, you can interact with it. Read more on how to
 
 For more information about the vulnerabilities database update, check the
 [maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).
+
+<!-- ## 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/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md
index 4cd3fc5f735..ac8c1ac0354 100644
--- a/doc/user/application_security/security_dashboard/index.md
+++ b/doc/user/application_security/security_dashboard/index.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # GitLab Security Dashboard **(ULTIMATE)**
 
 The Security Dashboard is a good place to get an overview of all the security
@@ -16,9 +20,9 @@ To benefit from the Security Dashboard you must first configure one of the
 The Security Dashboard supports the following reports:
 
 - [Container Scanning](../container_scanning/index.md)
-- [DAST](../dast/index.md)
+- [Dynamic Application Security Testing](../dast/index.md)
 - [Dependency Scanning](../dependency_scanning/index.md)
-- [SAST](../sast/index.md)
+- [Static Application Security Testing](../sast/index.md)
 
 ## Requirements
 
@@ -43,7 +47,7 @@ for your project. Use it to find and fix vulnerabilities affecting the
 ## Group Security Dashboard
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6709) in
-  [GitLab Ultimate](https://about.gitlab.com/pricing) 11.5.
+> [GitLab Ultimate](https://about.gitlab.com/pricing) 11.5.
 
 The group Security Dashboard gives an overview of the vulnerabilities of all the
 projects in a group and its subgroups.
@@ -102,3 +106,15 @@ That way, reports are created even if no code change happens.
 When using [Auto DevOps](../../../topics/autodevops/index.md), use
 [special environment variables](../../../topics/autodevops/index.md#environment-variables)
 to configure daily security scans.
+
+<!-- ## 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. -->