Single source of truth for merge requestsdocs/ssot-merge-requests

- Edit pages under user/project/merge_requests and
  add the relevant types in the frontmatter.
- Clean up descriptions.

Based on https://gitlab.com/groups/gitlab-org/-/epics/1280

14 files changed, 263 insertions, 91 deletions

diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md
index da6e6b5fd3a..e94125e658d 100644
--- a/doc/user/project/merge_requests/allow_collaboration.md
+++ b/doc/user/project/merge_requests/allow_collaboration.md
@@ -1,3 +1,7 @@
+---
+type: reference, howto
+---
+
 # Allow collaboration on merge requests across forks
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17395)
@@ -70,3 +74,15 @@ Here's how the process would look like:
    Note the colon (`:`) between the two branches. The above command will push the
    local branch `thedude-awesome-project-update-docs` to the
    `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository.
+
+<!-- ## 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/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md
index 79444ee5682..0579e3568da 100644
--- a/doc/user/project/merge_requests/authorization_for_merge_requests.md
+++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md
@@ -1,8 +1,12 @@
+---
+type: concepts
+---
+
 # Authorization for Merge requests
 
 There are two main ways to have a merge request flow with GitLab:
 
-1. Working with [protected branches] in a single repository.
+1. Working with [protected branches](../protected_branches.md) in a single repository.
 1. Working with forks of an authoritative project.
 
 ## Protected branch flow
@@ -53,4 +57,14 @@ forks.
 - The project need to keep their forks up to date, which requires more advanced
   Git skills (managing multiple remotes).
 
-[protected branches]: ../protected_branches.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/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md
index 65ee2e128ae..f6c4f767e3c 100644
--- a/doc/user/project/merge_requests/browser_performance_testing.md
+++ b/doc/user/project/merge_requests/browser_performance_testing.md
@@ -1,14 +1,18 @@
+---
+type: reference, howto
+---
+
 # Browser Performance Testing **[PREMIUM]**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3507)
 in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3.
 
-## Overview
-
 If your application offers a web interface and you are using
 [GitLab CI/CD](../../../ci/README.md), you can quickly determine the performance
 impact of pending code changes.
 
+## Overview
+
 GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source
 tool for measuring the performance of web sites, and has built a simple
 [Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance)
@@ -52,3 +56,15 @@ Consecutive merge requests will have something to compare to and the Performance
 report will be shown properly.
 
 ![Performance Widget](img/browser_performance_testing.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/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md
index 06b3779668b..a5c191c150f 100644
--- a/doc/user/project/merge_requests/cherry_pick_changes.md
+++ b/doc/user/project/merge_requests/cherry_pick_changes.md
@@ -1,8 +1,11 @@
-# Cherry-pick changes
+---
+type: reference, concepts
+---
 
-> [Introduced][ce-3514] in GitLab 8.7.
+# Cherry-pick changes
 
-GitLab implements Git's powerful feature to [cherry-pick any commit][git-cherry-pick]
+GitLab implements Git's powerful feature to
+[cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation")
 with introducing a **Cherry-pick** button in merge requests and commit details.
 
 ## Cherry-picking a merge request
@@ -18,9 +21,9 @@ where you can choose to either:
 - Cherry-pick the changes directly into the selected branch.
 - Create a new merge request with the cherry-picked changes.
 
-## Cherry-picking a Commit
+## Cherry-picking a commit
 
-You can cherry-pick a Commit from the Commit details page:
+You can cherry-pick a commit from the commit details page:
 
 ![Cherry-pick commit](img/cherry_pick_changes_commit.png)
 
@@ -39,5 +42,14 @@ mainline:
 git cherry-pick -m 2 7a39eb0
 ```
 
-[ce-3514]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3514 "Cherry-pick button Merge Request"
-[git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation"
+<!-- ## 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/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md
index 705ff333579..c3c2bdd94b3 100644
--- a/doc/user/project/merge_requests/code_quality.md
+++ b/doc/user/project/merge_requests/code_quality.md
@@ -1,14 +1,16 @@
+---
+type: reference, howto
+---
+
 # Code Quality **[STARTER]**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1984)
 in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3.
 
-## Overview
-
-If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your
+With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your
 source code quality using GitLab Code Quality.
 Code Quality uses [Code Climate Engines](https://codeclimate.com), which are
-free and open source. Code Quality doesn’t require a Code Climate subscription.
+free and open source. Code Quality doesn't require a Code Climate subscription.
 
 Going a step further, GitLab can show the Code Quality report right
 in the merge request widget area:
@@ -69,14 +71,24 @@ example on [analyzing a project's code quality](../../../ci/examples/code_qualit
 GitLab then checks this report, compares the metrics between the source and target
 branches, and shows the information right on the merge request.
 
-CAUTION: **Caution:**
 If multiple jobs in a pipeline generate a code quality artifact, only the artifact from
 the last created job (the job with the largest job ID) is used. To avoid confusion,
 configure only one job to generate a code quality artifact.
 
-NOTE: **Note:**
 If the Code Quality report doesn't have anything to compare to, no information
 will be displayed in the merge request area. That is the case when you add the
 Code Quality job in your `.gitlab-ci.yml` for the very first time.
 Consecutive merge requests will have something to compare to and the Code Quality
 report will be shown properly.
+
+<!-- ## 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/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md
index 3cd91a185e3..4f3c68090e4 100644
--- a/doc/user/project/merge_requests/fast_forward_merge.md
+++ b/doc/user/project/merge_requests/fast_forward_merge.md
@@ -1,21 +1,24 @@
+---
+type: reference, concepts
+---
+
 # Fast-forward merge requests
 
-Retain a linear Git history and a way to accept merge requests without
-creating merge commits.
+Sometimes, a workflow policy might mandate a clean commit history without
+merge commits. In such cases, the fast-forward merge is the perfect candidate.
+
+With fast-forward merge requests, you can retain a linear Git history and a way
+to accept merge requests without creating merge commits.
 
 ## Overview
 
-When the fast-forward merge ([`--ff-only`][ffonly]) setting is enabled, no merge
-commits will be created and all merges are fast-forwarded, which means that
-merging is only allowed if the branch could be fast-forwarded.
+When the fast-forward merge
+([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting
+is enabled, no merge commits will be created and all merges are fast-forwarded,
+which means that merging is only allowed if the branch could be fast-forwarded.
 
 When a fast-forward merge is not possible, the user is given the option to rebase.
 
-## Use cases
-
-Sometimes, a workflow policy might mandate a clean commit history without
-merge commits. In such cases, the fast-forward merge is the perfect candidate.
-
 ## Enabling fast-forward merges
 
 1. Navigate to your project's **Settings** and search for the 'Merge method'
@@ -32,4 +35,14 @@ source branch locally before you will be able to do a fast-forward merge.
 
 ![Fast forward merge rebase locally](img/ff_merge_rebase_locally.png)
 
-[ffonly]: https://git-scm.com/docs/git-merge#git-merge---ff-only
+<!-- ## 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/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index c6f4798e0d2..301fe095be5 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -1,3 +1,7 @@
+---
+type: index, reference, concepts
+---
+
 # Merge requests
 
 Merge requests allow you to exchange changes you made to source code and
diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md
index 2e9db949890..fd151a6df45 100644
--- a/doc/user/project/merge_requests/merge_request_approvals.md
+++ b/doc/user/project/merge_requests/merge_request_approvals.md
@@ -1,7 +1,23 @@
+---
+type: reference, concepts
+---
+
 # Merge request approvals **[STARTER]**
 
 > Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only).
 
+Merge request approvals enable enforced code review by requiring specified people
+to approve a merge request before it can be unblocked for merging.
+
+## Use cases
+
+1. Enforcing review of all code that gets merged into a repository.
+2. Specifying code maintainers for an entire repository.
+3. Specifying reviewers for a given proposed code change.
+4. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes.
+
+## Enabling the new approvals interface
+
 NOTE: **Note:**
 Prior to 12.0, if you are running a self-managed instance, the new interface shown on
 this page will not be available unless the feature flag
@@ -21,20 +37,6 @@ sudo -u git -H bin/rails console RAILS_ENV=production
 
 Then run `Feature.enable(:approval_rules)` to enable the feature flag.
 
-The documentation for the older interface can be accessed
-[here](/11.7/ee/user/project/merge_requests/merge_request_approvals.html).
-
-## Overview
-
-Merge request approvals enable enforced code review by requiring specified people to approve a merge request before it can be unblocked for merging.
-
-## Use cases
-
-1. Enforcing review of all code that gets merged into a repository.
-2. Specifying code maintainers for an entire repository.
-3. Specifying reviewers for a given proposed code change.
-4. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes.
-
 ## Editing approvals
 
 To edit the merge request approvals:
@@ -328,3 +330,15 @@ To filter merge requests by an individual approver, you can type (or select from
 the dropdown) `approver` and select the user.
 
 ![Filter MRs by an approver](img/filter_approver_merge_requests.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/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md
index 1477e35dca8..c93c7a5fe08 100644
--- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md
+++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md
@@ -1,3 +1,7 @@
+---
+type: reference, concepts
+---
+
 # Merge when pipeline succeeds
 
 When reviewing a merge request that looks ready to merge but still has one or
@@ -7,6 +11,8 @@ finish and remember to merge the request manually.
 
 ![Enable](img/merge_when_pipeline_succeeds_enable.png)
 
+## How it works
+
 When you hit the "Merge When Pipeline Succeeds" button, the status of the merge
 request will be updated to represent the impending merge. If you cannot wait
 for the pipeline to succeed and want to merge immediately, this option is
@@ -29,9 +35,6 @@ changes to be reviewed.
 
 ## Only allow merge requests to be merged if the pipeline succeeds
 
-> **Note:**
-You need to have jobs configured to enable this feature.
-
 You can prevent merge requests from being merged if their pipeline did not succeed
 or if there are discussions to be resolved.
 
@@ -39,9 +42,21 @@ Navigate to your project's settings page and expand the **Merge requests** secti
 In the **Merge checks** subsection, select the **Pipelines must succeed** check
 box and hit **Save** for the changes to take effect.
 
-![Pipelines must succeed settings](img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png)
+![Pipelines must succeed settings](img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png)
 
 From now on, every time the pipeline fails you will not be able to merge the
 merge request from the UI, until you make all relevant jobs pass.
 
 ![Only allow merge if pipeline succeeds message](img/merge_when_pipeline_succeeds_only_if_succeeds_msg.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/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md
index ccef2853e3f..6a0f2d18629 100644
--- a/doc/user/project/merge_requests/resolve_conflicts.md
+++ b/doc/user/project/merge_requests/resolve_conflicts.md
@@ -1,3 +1,7 @@
+---
+type: reference, concepts
+---
+
 # Merge request conflict resolution
 
 Merge conflicts occur when two branches have different changes that cannot be
@@ -66,3 +70,15 @@ Additionally, GitLab does not detect conflicts in renames away from a path. For
 example, this will not create a conflict: on branch `a`, doing `git mv file1
 file2`; on branch `b`, doing `git mv file1 file3`. Instead, both files will be
 present in the branch after the merge request is merged.
+
+<!-- ## 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/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md
index b9102798a49..950ec61f4ae 100644
--- a/doc/user/project/merge_requests/revert_changes.md
+++ b/doc/user/project/merge_requests/revert_changes.md
@@ -1,11 +1,13 @@
-# Reverting changes
+---
+type: reference, concepts
+---
 
-> [Introduced][ce-1990] in GitLab 8.5.
+# Reverting changes
 
-GitLab implements Git's powerful feature to [revert any commit][git-revert]
+GitLab implements Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation")
 with introducing a **Revert** button in merge requests and commit details.
 
-## Reverting a Merge Request
+## Reverting a merge request
 
 NOTE: **Note:**
 The **Revert** button will only be available for merge requests
@@ -30,9 +32,9 @@ create a new merge request with the revert changes.
 After the merge request has been reverted, the **Revert** button will not be
 available anymore.
 
-## Reverting a Commit
+## Reverting a commit
 
-You can revert a Commit from the Commit details page:
+You can revert a commit from the commit details page:
 
 ![Revert commit](img/cherry_pick_changes_commit.png)
 
@@ -54,5 +56,14 @@ mainline:
 git revert -m 2 7a39eb0
 ```
 
-[ce-1990]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1990 "Revert button Merge Request"
-[git-revert]: https://git-scm.com/docs/git-revert "Git revert documentation"
+<!-- ## 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/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md
index 4ff8ec3a7e6..39fd2588811 100644
--- a/doc/user/project/merge_requests/squash_and_merge.md
+++ b/doc/user/project/merge_requests/squash_and_merge.md
@@ -1,8 +1,14 @@
+---
+type: reference, concepts
+---
+
 # Squash and merge
 
-> [Introduced][ee-1024] in [GitLab Starter][ee] 8.17, and in [GitLab Core][ce] [11.0][ce-18956].
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1024) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.17.
+> - [Ported](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18956) to GitLab Core 11.0.
 
-Combine all commits of your merge request into one and retain a clean history.
+With squash and merge you can combine all your merge request's commits into one
+and retain a clean history.
 
 ## Overview
 
@@ -12,11 +18,11 @@ and then merges that commit using the merge method set for the project.
 
 In other words, squashing a merge request turns a long list of commits:
 
-![List of commits from a merge request][mr-commits]
+![List of commits from a merge request](img/squash_mr_commits.png)
 
 Into a single commit on merge:
 
-![A squashed commit followed by a merge commit][squashed-commit]
+![A squashed commit followed by a merge commit](img/squash_squashed_commit.png)
 
 The squashed commit's commit message will be either:
 
@@ -44,20 +50,18 @@ all you have to do is enable squashing before you press merge to join
 the commits in the merge request into a single commit.
 
 This way, the history of your base branch remains clean with
-meaningful commit messages and is simpler to [revert] if necessary.
+meaningful commit messages and is simpler to [revert](revert_changes.md) if necessary.
 
 ## Enabling squash for a merge request
 
 Anyone who can create or edit a merge request can choose for it to be squashed
 on the merge request form:
 
-![Squash commits checkbox on edit form][squash-edit-form]
-
----
+![Squash commits checkbox on edit form](img/squash_edit_form.png)
 
 This can then be overridden at the time of accepting the merge request:
 
-![Squash commits checkbox on accept merge request form][squash-mr-widget]
+![Squash commits checkbox on accept merge request form](img/squash_mr_widget.png)
 
 ## Commit metadata for squashed commits
 
@@ -69,19 +73,20 @@ The squashed commit has the following metadata:
 
 ## Squash and fast-forward merge
 
-When a project has the [fast-forward merge setting enabled][ff-merge], the merge
+When a project has the [fast-forward merge setting enabled](fast_forward_merge.md#enabling-fast-forward-merges), the merge
 request must be able to be fast-forwarded without squashing in order to squash
 it. This is because squashing is only available when accepting a merge request,
 so a merge request may need to be rebased before squashing, even though
 squashing can itself be considered equivalent to rebasing.
 
-[ee-1024]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1024
-[ce-18956]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18956
-[mr-commits]: img/squash_mr_commits.png
-[squashed-commit]: img/squash_squashed_commit.png
-[squash-edit-form]: img/squash_edit_form.png
-[squash-mr-widget]: img/squash_mr_widget.png
-[ff-merge]: fast_forward_merge.md#enabling-fast-forward-merges
-[ce]: https://about.gitlab.com/pricing/
-[ee]: https://about.gitlab.com/pricing/
-[revert]: revert_changes.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/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md
index 70bd1e60594..fbe216c3aed 100644
--- a/doc/user/project/merge_requests/versions.md
+++ b/doc/user/project/merge_requests/versions.md
@@ -1,13 +1,8 @@
-# Merge requests versions
+---
+type: reference, concepts
+---
 
-> **Notes:**
->
-> - [Introduced][ce-5467] in GitLab 8.12.
-> - Comments are disabled while viewing outdated merge versions or comparing to
->   versions other than base.
-> - Merge request versions are based on push not on commit. So, if you pushed 5
->   commits in a single push, it will be a single option in the dropdown. If you
->   pushed 5 times, that will count for 5 options.
+# Merge requests versions
 
 Every time you push to a branch that is tied to a merge request, a new version
 of merge request diff is created. When you visit a merge request that contains
@@ -16,25 +11,38 @@ request diffs.
 
 ![Merge request versions](img/versions.png)
 
----
+## Selecting a version
 
 By default, the latest version of changes is shown. However, you
 can select an older one from version dropdown.
 
 ![Merge request versions dropdown](img/versions_dropdown.png)
 
----
+Merge request versions are based on push not on commit. So, if you pushed 5
+commits in a single push, it will be a single option in the dropdown. If you
+pushed 5 times, that will count for 5 options.
 
 You can also compare the merge request version with an older one to see what has
 changed since then.
 
 ![Merge request versions compare](img/versions_compare.png)
 
----
+Comments are disabled while viewing outdated merge versions or comparing to
+versions other than base.
 
 Every time you push new changes to the branch, a link to compare the last
 changes appears as a system note.
 
 ![Merge request versions system note](img/versions_system_note.png)
 
-[ce-5467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5467
+<!-- ## 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/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md
index 6f33eb9a482..9cd868067bc 100644
--- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md
+++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md
@@ -1,4 +1,8 @@
-# "Work In Progress" Merge Requests
+---
+type: reference, concepts
+---
+
+# "Work In Progress" merge requests
 
 If a merge request is not yet ready to be merged, perhaps due to continued development
 or open discussions, you can prevent it from being accepted before it's ready by flagging
@@ -7,7 +11,7 @@ being merged, and it will stay disabled until the "WIP" flag has been removed.
 
 ![Blocked Accept Button](img/wip_blocked_accept_button.png)
 
-## Adding the "Work In Progress" flag to a Merge Request
+## Adding the "Work In Progress" flag to a merge request
 
 There are several ways to flag a merge request as a Work In Progress:
 
@@ -21,7 +25,7 @@ There are several ways to flag a merge request as a Work In Progress:
   source branch. This is not a toggle, and doing it again in another commit will have
   no effect.
 
-## Removing the "Work In Progress" flag from a Merge Request
+## Removing the "Work In Progress" flag from a merge request
 
 Similar to above, when a Merge Request is ready to be merged, you can remove the
 "Work in Progress" flag in several ways:
@@ -37,10 +41,22 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the
   Must have at least Developer level permissions on the project for the button to
   be visible.
 
-## Including/Excluding WIP Merge Requests when searching
+## Including/excluding WIP merge requests when searching
 
 When viewing/searching the merge requests list, you can choose to include or exclude
 WIP merge requests by adding a "WIP" filter in the search box, and choosing "Yes"
 (to include) or "No" (to exclude).
 
 ![Filter WIP MRs](img/filter_wip_merge_requests.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. -->