move "share projects with groups" docs

- correct the file tree
- remove duplicate doc
- move to project/members/
- move images
- update links

5 files changed, 42 insertions, 1 deletions

diff --git a/doc/user/project/members/img/max_access_level.png b/doc/user/project/members/img/max_access_level.png
new file mode 100644
index 00000000000..63f33f9d91d
--- /dev/null
+++ b/doc/user/project/members/img/max_access_level.png
diff --git a/doc/user/project/members/img/other_group_sees_shared_project.png b/doc/user/project/members/img/other_group_sees_shared_project.png
new file mode 100644
index 00000000000..67af27043eb
--- /dev/null
+++ b/doc/user/project/members/img/other_group_sees_shared_project.png
diff --git a/doc/user/project/members/img/share_project_with_groups.png b/doc/user/project/members/img/share_project_with_groups.png
new file mode 100644
index 00000000000..3cb4796f9f7
--- /dev/null
+++ b/doc/user/project/members/img/share_project_with_groups.png
diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md
index f1e6e3d947b..b8dd96087f1 100644
--- a/doc/user/project/members/index.md
+++ b/doc/user/project/members/index.md
@@ -113,4 +113,4 @@ If you change your mind before your request is approved, just click the
 
 ## Share project with group
 
-Alternatively, you can [share a project with an entire group](share_project_with_group.md) instead of adding users one by one.
+Alternatively, you can [share a project with an entire group](share_project_with_groups.md) instead of adding users one by one.
diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md
new file mode 100644
index 00000000000..4c1ddcdcba8
--- /dev/null
+++ b/doc/user/project/members/share_project_with_groups.md
@@ -0,0 +1,41 @@
+# Share Projects with other Groups
+
+You can share projects with other [groups](../../group/index.md). This makes it
+possible to add a group of users to a project with a single action.
+
+## Groups as collections of users
+
+Groups are used primarily to [create collections of projects](../user/group/index.md), but you can also
+take advantage of the fact that groups define collections of _users_, namely the group
+members.
+
+## Sharing a project with a group of users
+
+The primary mechanism to give a group of users, say 'Engineering', access to a project,
+say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project
+Acme'.  But what if 'Project Acme' already belongs to another group, say 'Open Source'?
+This is where the group sharing feature can be of use.
+
+To share 'Project Acme' with the 'Engineering' group, go to the project settings page for 'Project Acme' and use the left navigation menu to go to the 'Groups' section.
+
+![The 'Groups' section in the project settings screen](img/share_project_with_groups.png)
+
+Now you can add the 'Engineering' group with the maximum access level of your choice.
+After sharing 'Project Acme' with 'Engineering', the project is listed on the group dashboard.
+
+!['Project Acme' is listed as a shared project for 'Engineering'](img/other_group_sees_shared_project.png)
+
+## Maximum access level
+
+!['Project Acme' is shared with 'Engineering' with a maximum access level of 'Developer'](img/max_access_level.png)
+
+In the screenshot above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Master' or 'Owner') will only have 'Developer' access to 'Project Acme'.
+
+## Share project with group lock (EES/EEP)
+
+In [GitLab Enterprise Edition Starter](https://about.gitlab.com/gitlab-ee/)
+it is possible to prevent projects in a group from [sharing
+a project with another group](../members/share_project_with_groups.md).
+This allows for tighter control over project access.
+
+Learn more about [Share with group lock](https://docs.gitlab.com/ee/user/group/index.html#share-with-group-lock-ees-eep).