Merge branch 'selhorn-groups-take1' into 'master'

Edited top section of topic

See merge request gitlab-org/gitlab!54524

doc/ci/environments/protected_environments.md

@@ -70,7 +70,7 @@ Alternatively, you can use the API to protect an environment:
      name: ${CI_JOB_NAME}
    ```
 
-1. Use the UI to [create a new group](../../user/group/index.md#create-a-new-group).
+1. Use the UI to [create a new group](../../user/group/index.md#create-a-group).
    For example, this group is called `protected-access-group` and has the group ID `9899826`. Note
    that the rest of the examples in these steps use this group.
 

doc/gitlab-basics/index.md

@@ -23,7 +23,7 @@ The following are guides to basic GitLab functionality:
 
 - [Create and add your SSH public key](../ssh/README.md), for enabling Git over SSH.
 - [Create a project](../user/project/working_with_projects.md#create-a-project), to start using GitLab.
-- [Create a group](../user/group/index.md#create-a-new-group), to combine and administer
+- [Create a group](../user/group/index.md#create-a-group), to combine and administer
   projects together.
 - [Create a branch](create-branch.md), to make changes to files stored in a project's repository.
 - [Feature branch workflow](feature_branch_workflow.md).

doc/intro/index.md

@@ -12,7 +12,7 @@ comments: false
 Create projects and groups.
 
 - [Create a new project](../user/project/working_with_projects.md#create-a-project)
-- [Create a new group](../user/group/index.md#create-a-new-group)
+- [Create a new group](../user/group/index.md#create-a-group)
 
 ## Prioritize
 

doc/user/admin_area/index.md

@@ -203,7 +203,7 @@ sort order is by **Last created**.
 To search for groups by name, enter your criteria in the search field. The group search is case
 insensitive, and applies partial matching.
 
-To [Create a new group](../group/index.md#create-a-new-group) click **New group**.
+To [Create a new group](../group/index.md#create-a-group) click **New group**.
 
 ### Administering Jobs
 

doc/user/group/index.md

@@ -7,54 +7,34 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Groups
 
-With GitLab Groups, you can:
+In GitLab, you can put related projects together in a group.
 
-- Assemble related projects together.
-- Grant members access to several projects at once.
+For example, you might create a group for your company members and a subgroup for each individual team.
+You can name the group `company-team`, and the subgroups `backend-team`, `frontend-team`, and `production-team`.
 
-For a video introduction to GitLab Groups, see [GitLab University: Repositories, Projects and Groups](https://www.youtube.com/watch?v=4TWfh1aKHHw).
+Then you can:
 
-Groups can also be nested in [subgroups](subgroups/index.md).
+- Grant members access to multiple projects at once.
+- Add to-do items for all of the group members at once.
+- View the [issues](../project/issues/index.md#issues-list) and
+  [merge requests](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group)
+  for all projects in the group, together in a single list view.
+- [Bulk edit](../group/bulk_editing/index.md) issues, epics, and merge requests.
 
-Find your groups by clicking **Groups > Your Groups** in the top navigation.
+You can also create [subgroups](subgroups/index.md).
 
-![GitLab Groups](img/groups.png)
+## View groups
 
-> The **Groups** dropdown in the top navigation was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36234) in [GitLab 11.1](https://about.gitlab.com/releases/2018/07/22/gitlab-11-1-released/#groups-dropdown-in-navigation).
+To view groups:
 
-The **Groups** page displays:
+1. In the top menu, select **Groups > Your Groups**. All groups you are a member of are displayed.
+1. To view a list of public groups, select **Explore public groups**.
 
-- All groups you are a member of, when **Your groups** is selected.
-- A list of public groups, when **Explore public groups** is selected.
+You can also view groups by namespace.
 
-Each group on the **Groups** page is listed with:
+### Namespaces
 
-- How many subgroups it has.
-- How many projects it contains.
-- How many members the group has, not including members inherited from parent group(s).
-- The group's visibility.
-- A link to the group's settings, if you have sufficient permissions.
-- A link to leave the group, if you are a member.
-
-## Use cases
-
-You can create groups for numerous reasons. To name a couple:
-
-- Grant access to multiple projects and multiple team members in fewer steps by organizing related projects under the same [namespace](#namespaces) and adding members to the top-level group.
-- Make it easier to `@mention` all of your team at once in issues and merge requests by creating a group and including the appropriate members.
-
-For example, you could create a group for your company members, and create a [subgroup](subgroups/index.md) for each individual team. Let's say you create a group called `company-team`, and you create subgroups in this group for the individual teams `backend-team`, `frontend-team`, and `production-team`.
-
-- When you start a new implementation from an issue, you add a comment:
-  _"`@company-team`, let's do it! `@company-team/backend-team` you're good to go!"_
-- When your backend team needs help from frontend, they add a comment:
-  _"`@company-team/frontend-team` could you help us here please?"_
-- When the frontend team completes their implementation, they comment:
-  _"`@company-team/backend-team`, it's done! Let's ship it `@company-team/production-team`!"_
-
-## Namespaces
-
-In GitLab, a namespace is a unique name to be used as a user name, a group name, or a subgroup name.
+In GitLab, a namespace is a unique name and URL for a user, a group, or subgroup.
 
 - `http://gitlab.example.com/username`
 - `http://gitlab.example.com/groupname`
@@ -62,35 +42,19 @@ In GitLab, a namespace is a unique name to be used as a user name, a group name,
 
 For example, consider a user named Alex:
 
-1. Alex creates an account on GitLab.com with the username `alex`;
-   their profile will be accessed under `https://gitlab.example.com/alex`
-1. Alex creates a group for their team with the group name `alex-team`;
-   the group and its projects will be accessed under `https://gitlab.example.com/alex-team`
-1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`;
-   this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing`
-
-By doing so:
-
-- Any team member mentions Alex with `@alex`
-- Alex mentions everyone from their team with `@alex-team`
-- Alex mentions only the marketing team with `@alex-team/marketing`
+1. Alex creates an account with the username `alex`: `https://gitlab.example.com/alex`
+1. Alex creates a group for their team with the group name `alex-team`.
+   The group and its projects are available at: `https://gitlab.example.com/alex-team`
+1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`.
+   The subgroup and its projects are available at: `https://gitlab.example.com/alex-team/marketing`
 
-## Issues and merge requests within a group
+## Create a group
 
-Issues and merge requests are part of projects. For a given group, you can view all of the
-[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group) across all projects in that group,
-together in a single list view.
-
-### Bulk editing issues and merge requests
-
-For details, see [bulk editing issues and merge requests](../group/bulk_editing/index.md).
-
-## Create a new group
-
-> For a list of words that are not allowed to be used as group names see the
-> [reserved names](../reserved_names.md).
+NOTE:
+For a list of words that can not be used as group names, see
+[reserved names](../reserved_names.md).
 
-To create a new Group, either:
+To create a new group, either:
 
 - In the top menu, click **Groups** and then **Your Groups**, and click the green button **New group**.
 
@@ -166,7 +130,7 @@ If you change your mind before your request is approved, just click the
 
 ![Withdraw access request button](img/withdraw_access_request_button.png)
 
-## Changing the owner of a group
+## Change the owner of a group
 
 Ownership of a group means at least one of its members has
 [Owner permission](../permissions.md#group-members-permissions). Groups must have at
@@ -266,6 +230,18 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last
 
 ![Group members sort](img/group_members_sort_13_7.png)
 
+## Mention a group in an issue or merge request
+
+When you mention a group in a comment, every member of the group gets a to-do item
+added to their To-do list.
+
+1. Open the MR or issue.
+1. In a comment, type `@` followed by the user, group, or subgroup namespace.
+   For example, `@alex`, `@alex-team`, or `@alex-team/marketing`.
+1. Select **Comment**.
+
+A to-do item is created for all the group and subgroup members.
+
 ## Changing the default branch protection of a group
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9.
@@ -520,7 +496,7 @@ the group's dashboard, and clicking **Settings**.
 ### General settings
 
 In addition to editing any settings you previously
-set when [creating the group](#create-a-new-group), you can also
+set when [creating the group](#create-a-group), you can also
 access further configurations for your group.
 
 #### Changing a group's path

doc/user/project/clusters/protect/container_host_security/quick_start_guide.md

@@ -15,7 +15,7 @@ applications through GMAv2 exclusively when using Container Network Security.
 The following steps are recommended to install and use Container Host Security through GitLab:
 
 1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/).
-1. [Create a group](../../../../group/#create-a-new-group).
+1. [Create a group](../../../../group/#create-a-group).
 1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md).
 1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md).
 

doc/user/project/clusters/protect/container_network_security/quick_start_guide.md

@@ -15,7 +15,7 @@ applications through GMAv2 exclusively when using Container Network Security.
 The following steps are recommended to install and use Container Network Security through GitLab:
 
 1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/).
-1. [Create a group](../../../../group/#create-a-new-group).
+1. [Create a group](../../../../group/#create-a-group).
 1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md).
 1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md).
 

doc/user/project/merge_requests/merge_request_approvals.md

@@ -138,14 +138,14 @@ to push or merge code to any branches.
 
 To enable this access:
 
-1. [Create a new group](../../group/index.md#create-a-new-group), and then
+1. [Create a new group](../../group/index.md#create-a-group), and then
    [add the user to the group](../../group/index.md#add-users-to-a-group),
    ensuring you select the Reporter role for the user.
 1. [Share the project with your group](../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users),
    based on the Reporter role.
 1. Navigate to your project's **Settings > General**, and in the
    **Merge request approvals** section, click **Expand**.
-1. [Add the group](../../group/index.md#create-a-new-group) to the permission list
+1. [Add the group](../../group/index.md#create-a-group) to the permission list
    for the protected branch.
 
 ![Update approval rule](img/update_approval_rule_v13_4.png)