Deprecate and split old doc on adding usersdocs/membership-refactor

[ci skip]

8 files changed, 114 insertions, 116 deletions

diff --git a/doc/user/membership.md b/doc/user/membership.md
index 5870000ccd2..310fc3c8de0 100644
--- a/doc/user/membership.md
+++ b/doc/user/membership.md
@@ -1,10 +1,17 @@
-# Membership to projects and groups
+# User membership to projects and groups
 
 GitLab's [permission model][permissions] allows users to have different
 abilities depending on the access level they have in a particular group or
-project. To manage the membership of project users you need at least Master
+project. You can manage the groups and users and their access levels in all of
+your projects as well as personalize the access level you give each user,
+per-project.
+
+To manage the membership of project users you need at least Master
 permission, whereas for groups you need to be an Owner.
 
+The first step to add or import a user, go to your project and click on
+**Members** in the drop-down menu on the right side of your screen.
+
 ## Add a user to a project
 
 [Read more about adding a user to a project.](membership/add_a_user_to_a_project.md)
@@ -27,10 +34,17 @@ permission, whereas for groups you need to be an Owner.
 
 ## Invite users using their email address
 
+If a user you want to give access to doesn't have an account on your GitLab
+instance, you can invite them just by typing their email address in the user
+search field.
+
 [Read more about inviting users using their email address.](membership/invite_users_using_their_email_address.md)
 
 ## Request access to a project or a group
 
+As a project owner you can enable or disable non members to request access to
+your project and as a user you can request to be a member of a project.
+
 [Read more about requesting access to a project or a group.](membership/request_access_to_a_project_or_a_group.md)
 
 ## Set an expiration date on memberships
diff --git a/doc/user/membership/add_a_user_to_a_project.md b/doc/user/membership/add_a_user_to_a_project.md
index e69de29bb2d..d3f5de5af65 100644
--- a/doc/user/membership/add_a_user_to_a_project.md
+++ b/doc/user/membership/add_a_user_to_a_project.md
@@ -0,0 +1,25 @@
+# Add a user to a project
+
+Right next to **People**, start typing the name or username of the user you
+want to add.
+
+![Search for people](img/membership_add_user_to_project_search.png)
+
+---
+
+Select the user and the [permission level](../../user/permissions.md)
+that you'd like to give the user. Note that you can select more than one user.
+
+![Give user permissions](img/add_user_give_permissions.png)
+
+---
+
+Once done, hit **Add users to project** and they will be immediately added to
+your project with the permissions you gave them above.
+
+![List members](img/add_user_list_members.png)
+
+---
+
+From there on, you can either remove an existing user or change their access
+level to the project.
diff --git a/doc/user/membership/img/membership_add_user_to_project_search.png b/doc/user/membership/img/membership_add_user_to_project_search.png
new file mode 100644
index 00000000000..6826ba1c3a5
--- /dev/null
+++ b/doc/user/membership/img/membership_add_user_to_project_search.png
diff --git a/doc/user/membership/import_users_from_another_project.md b/doc/user/membership/import_users_from_another_project.md
index e69de29bb2d..45c94a6f622 100644
--- a/doc/user/membership/import_users_from_another_project.md
+++ b/doc/user/membership/import_users_from_another_project.md
@@ -0,0 +1,20 @@
+# Import users from another project
+
+You should have `master` or `owner` permissions to add or import a new user
+to your project.
+
+You can import another project's users in your own project by hitting the
+**Import members** button on the upper right corner of the **Members** menu.
+
+In the dropdown menu, you can see only the projects you are Master on.
+
+![Import members from another project](img/add_user_import_members_from_another_project.png)
+
+---
+
+Select the one you want and hit **Import project members**. A flash message
+notifying you that the import was successful will appear, and the new members
+are now in the project's members list. Notice that the permissions that they
+had on the project you imported from are retained.
+
+![Members list of new members](img/add_user_imported_members.png)
diff --git a/doc/user/membership/invite_users_using_their_email_address.md b/doc/user/membership/invite_users_using_their_email_address.md
index e69de29bb2d..565adcf1e09 100644
--- a/doc/user/membership/invite_users_using_their_email_address.md
+++ b/doc/user/membership/invite_users_using_their_email_address.md
@@ -0,0 +1,27 @@
+## Invite people using their email address
+
+If a user you want to give access to doesn't have an account on your GitLab
+instance, you can invite them just by typing their e-mail address in the
+user search field.
+
+![Invite user by mail](img/add_user_email_search.png)
+
+---
+
+As you can imagine, you can mix inviting multiple people and adding existing
+GitLab users to the project.
+
+![Invite user by mail ready to submit](img/add_user_email_ready.png)
+
+---
+
+Once done, hit **Add users to project** and watch that there is a new member
+with the e-mail address we used above. From there on, you can resend the
+invitation, change their access level or even delete them.
+
+![Invite user members list](img/add_user_email_accept.png)
+
+---
+
+Once the user accepts the invitation, they will be prompted to create a new
+GitLab account using the same e-mail address the invitation was sent to.
diff --git a/doc/user/membership/request_access_to_a_project_or_a_group.md b/doc/user/membership/request_access_to_a_project_or_a_group.md
index e69de29bb2d..d43c68fb48a 100644
--- a/doc/user/membership/request_access_to_a_project_or_a_group.md
+++ b/doc/user/membership/request_access_to_a_project_or_a_group.md
@@ -0,0 +1,24 @@
+## Request access to a project
+
+As a project owner you can enable or disable non members to request access to
+your project. Go to the project settings and click on **Allow users to request access**.
+
+As a user, you can request to be a member of a project. Go to the project you'd
+like to be a member of, and click the **Request Access** button on the right
+side of your screen.
+
+![Request access button](img/request_access_button.png)
+
+---
+
+Project owners & masters will be notified of your request and will be able to approve or
+decline it on the members page.
+
+![Manage access requests](img/access_requests_management.png)
+
+---
+
+If you change your mind before your request is approved, just click the
+**Withdraw Access Request** button.
+
+![Withdraw access request button](img/withdraw_access_request_button.png)
diff --git a/doc/workflow/README.md b/doc/workflow/README.md
index 2d9bfbc0629..218756c7246 100644
--- a/doc/workflow/README.md
+++ b/doc/workflow/README.md
@@ -14,7 +14,7 @@
 - [Notification emails](notifications.md)
 - [Project Features](project_features.md)
 - [Project forking workflow](forking_workflow.md)
-- [Project users](add-user/add-user.md)
+- [Project and group membership](../user/membership.md)
 - [Protected branches](../user/project/protected_branches.md)
 - [Slash commands](../user/project/slash_commands.md)
 - [Sharing a project with a group](share_with_group.md)
diff --git a/doc/workflow/add-user/add-user.md b/doc/workflow/add-user/add-user.md
index e541111d7b3..a4294e6d7fd 100644
--- a/doc/workflow/add-user/add-user.md
+++ b/doc/workflow/add-user/add-user.md
@@ -1,114 +1,2 @@
-# Project users
+This document was moved to [user/membership.md](../../user/membership.md).
 
-You can manage the groups and users and their access levels in all of your
-projects. You can also personalize the access level you give each user,
-per-project.
-
-You should have `master` or `owner` permissions to add or import a new user
-to your project.
-
-The first step to add or import a user, go to your project and click on
-**Members** in the drop-down menu on the right side of your screen.
-
-![Members](img/add_user_members_menu.png)
-
----
-
-## Add a user
-
-Right next to **People**, start typing the name or username of the user you
-want to add.
-
-![Search for people](img/add_user_search_people.png)
-
----
-
-Select the user and the [permission level](../../user/permissions.md)
-that you'd like to give the user. Note that you can select more than one user.
-
-![Give user permissions](img/add_user_give_permissions.png)
-
----
-
-Once done, hit **Add users to project** and they will be immediately added to
-your project with the permissions you gave them above.
-
-![List members](img/add_user_list_members.png)
-
----
-
-From there on, you can either remove an existing user or change their access
-level to the project.
-
-## Import users from another project
-
-You can import another project's users in your own project by hitting the
-**Import members** button on the upper right corner of the **Members** menu.
-
-In the dropdown menu, you can see only the projects you are Master on.
-
-![Import members from another project](img/add_user_import_members_from_another_project.png)
-
----
-
-Select the one you want and hit **Import project members**. A flash message
-notifying you that the import was successful will appear, and the new members
-are now in the project's members list. Notice that the permissions that they
-had on the project you imported from are retained.
-
-![Members list of new members](img/add_user_imported_members.png)
-
----
-
-## Invite people using their e-mail address
-
-If a user you want to give access to doesn't have an account on your GitLab
-instance, you can invite them just by typing their e-mail address in the
-user search field.
-
-![Invite user by mail](img/add_user_email_search.png)
-
----
-
-As you can imagine, you can mix inviting multiple people and adding existing
-GitLab users to the project.
-
-![Invite user by mail ready to submit](img/add_user_email_ready.png)
-
----
-
-Once done, hit **Add users to project** and watch that there is a new member
-with the e-mail address we used above. From there on, you can resend the
-invitation, change their access level or even delete them.
-
-![Invite user members list](img/add_user_email_accept.png)
-
----
-
-Once the user accepts the invitation, they will be prompted to create a new
-GitLab account using the same e-mail address the invitation was sent to.
-
-## Request access to a project
-
-As a project owner you can enable or disable non members to request access to
-your project. Go to the project settings and click on **Allow users to request access**.
-
-As a user, you can request to be a member of a project. Go to the project you'd
-like to be a member of, and click the **Request Access** button on the right
-side of your screen.
-
-![Request access button](img/request_access_button.png)
-
----
-
-Project owners & masters will be notified of your request and will be able to approve or
-decline it on the members page.
-
-![Manage access requests](img/access_requests_management.png)
-
----
-
-If you change your mind before your request is approved, just click the
-**Withdraw Access Request** button.
-
-![Withdraw access request button](img/withdraw_access_request_button.png)