Refactor protected branches documentation

6 files changed, 58 insertions, 29 deletions

diff --git a/doc/user/project/img/project_settings_list.png b/doc/user/project/img/project_settings_list.png
new file mode 100644
index 00000000000..57ca2ac5f9e
--- /dev/null
+++ b/doc/user/project/img/project_settings_list.png
diff --git a/doc/user/project/img/protected_branches_devs_can_push.png b/doc/user/project/img/protected_branches_devs_can_push.png
index a4f664d3b21..308743c3e80 100644
--- a/doc/user/project/img/protected_branches_devs_can_push.png
+++ b/doc/user/project/img/protected_branches_devs_can_push.png
diff --git a/doc/user/project/img/protected_branches_list.png b/doc/user/project/img/protected_branches_list.png
new file mode 100644
index 00000000000..9a5b973c423
--- /dev/null
+++ b/doc/user/project/img/protected_branches_list.png
diff --git a/doc/user/project/img/protected_branches_matches.png b/doc/user/project/img/protected_branches_matches.png
index 2a50cb174bb..f213f4f6a59 100644
--- a/doc/user/project/img/protected_branches_matches.png
+++ b/doc/user/project/img/protected_branches_matches.png
diff --git a/doc/user/project/img/protected_branches_page.png b/doc/user/project/img/protected_branches_page.png
index c00443803de..ec0683febee 100644
--- a/doc/user/project/img/protected_branches_page.png
+++ b/doc/user/project/img/protected_branches_page.png
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
index 54b0ffb4ecd..62a5fa105c2 100644
--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -1,55 +1,84 @@
 # Protected Branches
 
-Permissions in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches.
+[Permissions](../permissions.md) in GitLab are fundamentally defined around the
+idea of having read or write permission to the repository and branches. To
+prevent people from messing with history or pushing code without review, we've
+created protected branches.
 
-To prevent people from messing with history or pushing code without review, we've created protected branches.
+A protected branch does four simple things:
 
-A protected branch does three simple things:
+- it prevents its creation, if not already created, from everybody except users
+  with Master permission (or developers if configured)
+- it prevents pushes from everybody except users with Master permission (or
+  developers if configured)
+- it prevents **anyone** from force pushing to the branch
+- it prevents **anyone** from deleting the branch
 
-* it prevents pushes from everybody except users with Master permission
-* it prevents anyone from force pushing to the branch
-* it prevents anyone from deleting the branch
+## Configuring protected branches
 
-You can make any branch a protected branch. GitLab makes the master branch a protected branch by default.
+To protect a branch, you need to have at least Master permission level. The
+master branch is protected by default.
 
-To protect a branch, user needs to have at least a Master permission level, see [permissions document](../user/permissions.md).
+1. Navigate to the main page of the project.
+1. In the upper right corner, click the settings wheel and select **Protected branches**.
 
-![protected branches page](img/protected_branches_page.png)
+    ![Project settings list](img/project_settings_list.png)
 
-Navigate to project settings page and select `protected branches`. From the `Branch` dropdown menu select the branch you want to protect.
+1. From the **Branch** dropdown menu, select the branch you want to protect and
+   click **Protect**.
 
-Some workflows, like [GitLab workflow](gitlab_flow.md), require all users with write access to submit a Merge request in order to get the code into a protected branch.
+    ![Protected branches page](img/protected_branches_page.png)
 
-Since Masters and Owners can already push to protected branches, that means Developers cannot push to protected branch and need to submit a Merge request.
+1. Once done, the protected branch will appear in the "Already protected" list.
 
-However, there are workflows where that is not needed and only protecting from force pushes and branch removal is useful.
+    ![Protected branches list](img/protected_branches_list.png)
 
-For those workflows, you can allow everyone with write access to push to a protected branch by selecting `Developers can push` check box.
+---
 
-On already protected branches you can also allow developers to push to the repository by selecting the `Developers can push` check box.
+Some workflows, like the [GitLab workflow](../../workflow/gitlab_flow.md),
+require all users with write access to submit a Merge request in order to get
+the changes into a protected branch. Since Masters and Owners can already push
+to protected branches, that means Developers cannot push to them and need to
+submit a Merge request.
+
+However, there are workflows where that is not needed, and only protecting from
+force pushes and branch removal is useful. For those workflows, you can allow
+everyone with write access to push to a protected branch by selecting the
+"Developers can push" check box.
+
+You can set this option while creating a protected branch or afterwards by
+selecting the "Developers can push" check box.
 
 ![Developers can push](img/protected_branches_devs_can_push.png)
 
-## Wildcard Protected Branches
+## Wildcard protected branches
 
 >**Note:**
-This feature was added in GitLab 8.10.
+This feature was [introduced][ce-4665] in GitLab 8.10.
+
+You can specify a wildcard protected branch, which will protect all branches
+matching the wildcard. For example:
+
+| Wildcard Protected Branch | Matching Branches                                      |
+|---------------------------+--------------------------------------------------------|
+| `*-stable`                | `production-stable`, `staging-stable`                  |
+| `production/*`            | `production/app-server`, `production/load-balancer`    |
+| `*gitlab*`                | `gitlab`, `gitlab/staging`, `master/gitlab/production` |
 
-1. You can specify a wildcard protected branch, which will protect all branches matching the wildcard. For example:
+Protected branch settings (like "Developers can push") apply to all matching
+branches.
 
-    | Wildcard Protected Branch | Matching Branches                                      |
-    |---------------------------+--------------------------------------------------------|
-    | `*-stable`                | `production-stable`, `staging-stable`                  |
-    | `production/*`            | `production/app-server`, `production/load-balancer`    |
-    | `*gitlab*`                | `gitlab`, `gitlab/staging`, `master/gitlab/production` |
+Two different wildcards can potentially match the same branch. For example,
+`*-stable` and `production-*` would both match a `production-stable` branch.
+In that case, if _any_ of these protected branches have "Developers can push"
+set to true, then `production-stable` will also have set to true.
 
-1. Protected branch settings (like "Developers Can Push") apply to all matching branches.
+If you click on a protected branch's name, you will be presented with a list of
+all matching branches:
 
-1. Two different wildcards can potentially match the same branch. For example, `*-stable` and `production-*` would both match a `production-stable` branch.
-   >**Note:**
-   If _any_ of these protected branches have "Developers Can Push" set to true, then `production-stable` has it set to true.
+![Protected branch matches](img/protected_branches_matches.png)
 
-1. If you click on a protected branch's name, you will be presented with a list of all matching branches:
+## Restrict the creation of protected branches
 
-    ![protected branch matches](img/protected_branches_matches.png)
 
+[ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665