Rewrite the visibility page, part 1

doc/administration/geo/replication/location_aware_git_url.md

@@ -107,7 +107,7 @@ You can customize the:
 - SSH remote URL to use the location-aware `git.example.com`. To do so, change the SSH remote URL's
   host by setting `gitlab_rails['gitlab_ssh_host']` in `gitlab.rb` of web nodes.
 - HTTP remote URL as shown in
-  [Custom Git clone URL for HTTP(S)](../../../user/admin_area/settings/visibility_and_access_controls.md#custom-git-clone-url-for-https).
+  [Custom Git clone URL for HTTP(S)](../../../user/admin_area/settings/visibility_and_access_controls.md#customize-git-clone-url-for-https).
 
 ## Example Git request handling behavior
 

doc/administration/index.md

@@ -121,7 +121,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Creating users](../user/profile/account/create_accounts.md): Create users manually or through authentication integrations.
 - [Libravatar](libravatar.md): Use Libravatar instead of Gravatar for user avatars.
 - [Sign-up restrictions](../user/admin_area/settings/sign_up_restrictions.md): block email addresses of specific domains, or whitelist only specific domains.
-- [Access restrictions](../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols): Define which Git access protocols can be used to talk to GitLab (SSH, HTTP, HTTPS).
+- [Access restrictions](../user/admin_area/settings/visibility_and_access_controls.md#configure-enabled-git-access-protocols): Define which Git access protocols can be used to talk to GitLab (SSH, HTTP, HTTPS).
 - [Authentication and Authorization](auth/index.md): Configure external authentication with LDAP, SAML, CAS, and additional providers.
   - [Sync LDAP](auth/ldap/index.md)
   - [Kerberos authentication](../integration/kerberos.md)

doc/public_access/public_access.md

@@ -28,7 +28,7 @@ They are listed in the public access directory (`/public`) for all users.
 
 NOTE:
 By default, `/public` is visible to unauthenticated users. However, if the
-[**Public** visibility level](../user/admin_area/settings/visibility_and_access_controls.md#restricted-visibility-levels)
+[**Public** visibility level](../user/admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels)
 is restricted, `/public` is visible only to signed-in users.
 
 ## Internal projects
@@ -71,7 +71,7 @@ You can restrict the use of visibility levels for users when they create a proje
 This is useful to prevent users from publicly exposing their repositories by accident. The
 restricted visibility settings do not apply to admin users.
 
-For details, see [Restricted visibility levels](../user/admin_area/settings/visibility_and_access_controls.md#restricted-visibility-levels).
+For details, see [Restricted visibility levels](../user/admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels).
 
 <!-- ## Troubleshooting
 

doc/user/admin_area/settings/help_page.md

@@ -26,7 +26,7 @@ You can now see the message on `/help`.
 
 NOTE:
 By default, `/help` is visible to unauthenticated users. However, if the
-[**Public** visibility level](visibility_and_access_controls.md#restricted-visibility-levels)
+[**Public** visibility level](visibility_and_access_controls.md#restrict-visibility-levels)
 is restricted, `/help` is visible only to signed-in users.
 
 ## Add a help message to the sign-in page

doc/user/admin_area/settings/index.md

@@ -51,7 +51,7 @@ To access the default page for Admin Area settings:
 | Option | Description |
 | ------ | ----------- |
 | [Repository's custom initial branch name](../../project/repository/branches/default.md#instance-level-custom-initial-branch-name) | Set a custom branch name for new repositories created in your instance. |
-| [Repository mirror](visibility_and_access_controls.md#allow-mirrors-to-be-set-up-for-projects) | Configure repository mirroring. |
+| [Repository mirror](visibility_and_access_controls.md#enable-project-mirroring) | Configure repository mirroring. |
 | [Repository storage](../../../administration/repository_storage_types.md) | Configure storage path settings. |
 | Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. |
 | [Repository static objects](../../../administration/static_objects_external_storage.md) | Serve repository static objects (for example, archives and blobs) from an external storage (for example, a CDN). |

doc/user/admin_area/settings/visibility_and_access_controls.md

@@ -5,9 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated
 type: reference
 ---
 
-# Visibility and access controls **(FREE SELF)**
+# Control access and visibility **(FREE SELF)**
 
-GitLab allows administrators to enforce specific controls.
+GitLab enables users with the [Administrator role](../../permissions.md) to enforce
+specific controls on branches, projects, snippets, groups, and more.
 
 To access the visibility and access control options:
 
@@ -16,60 +17,84 @@ To access the visibility and access control options:
 1. In the left sidebar, select **Settings > General**.
 1. Expand the **Visibility and access controls** section.
 
-## Default branch protection
+## Protect default branches
 
-This global option defines the branch protection that applies to every repository's
-[default branch](../../project/repository/branches/default.md).
-[Branch protection](../../project/protected_branches.md) specifies which roles can push
-to branches and which roles can delete branches. In this case _Default_ refers to a
-repository's [default branch](../../project/repository/branches/default.md).
+With this option, you can define [branch protections](../../project/protected_branches.md)
+to apply to every repository's [default branch](../../project/repository/branches/default.md).
+These protections specify the user roles with permission to:
 
-This setting applies only to each repositories' default branch. To protect other branches, you must configure branch protection in repository. For details, see [protected branches](../../project/protected_branches.md).
+- Push to branches.
+- Delete branches.
 
-To change the default branch protection:
+This setting applies only to each repository's default branch. To protect other branches,
+you must configure [branch protection in the repository](../../project/protected_branches.md),
+or configure [branch protection for groups](../../group/index.md#change-the-default-branch-protection-of-a-group).
 
-1. Select the desired option.
-1. Click **Save changes**.
-
-For more details, see [Protected branches](../../project/protected_branches.md).
+To change the default branch protection for the entire instance:
 
-To change this setting for a specific group, see [Default branch protection for groups](../../group/index.md#change-the-default-branch-protection-of-a-group)
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. Select a **Default branch protection**:
+   - **Not protected** - Both developers and maintainers can push new commits,
+     force push, or delete the branch.
+   - **Protected against pushes** - Developers cannot push new commits, but are
+     allowed to accept merge requests to the branch. Maintainers can push to the branch.
+   - **Partially protected** - Both developers and maintainers can push new commits,
+     but cannot force push or delete the branch.
+   - **Fully protected** - Developers cannot push new commits, but maintainers can.
+     No one can force push or delete the branch.
+1. To allow group owners to override the instance's default branch protection, select
+   [**Allow owners to manage default branch protection per group**](#prevent-overrides-of-default-branch-protection).
+1. Select **Save changes**.
 
-### Disable group owners from updating default branch protection **(PREMIUM SELF)**
+### Prevent overrides of default branch protection **(PREMIUM SELF)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211944) in GitLab 13.0.
 
-By default, group owners are allowed to override the branch protection set at the global level.
-
-In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege of group owners.
-
-To do this:
+Instance-level protections for [default branch](../../project/repository/branches/default.md)
+can be overridden on a per-group basis by the group's owner. In
+[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can
+disable this privilege for group owners, enforcing the instance-level protection rule:
 
-1. Uncheck the **Allow owners to manage default branch protection per group** checkbox.
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. Deselect the **Allow owners to manage default branch protection per group** checkbox.
+1. Select **Save changes**.
 
 NOTE:
 GitLab administrators can still update the default branch protection of a group.
 
-## Default project creation protection
-
-Project creation protection specifies which roles can create projects.
-
-To change the default project creation protection:
-
-1. Select the desired option.
-1. Click **Save changes**.
+## Define which roles can create projects
 
-For more details, see [Specify who can add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group).
+Instance-level protections for project creation define which roles can
+[add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group)]
+on the instance. To alter which roles have permission to create projects:
 
-## Default project deletion protection **(PREMIUM SELF)**
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. For **Default project creation protection**, select the desired roles:
+   - No one.
+   - Maintainers.
+   - Developers and Maintainers.
+1. Select **Save changes**.
 
-By default, a project can be deleted by anyone with the **Owner** role, either at the project or
-group level.
+## Restrict project deletion to Administrators **(PREMIUM SELF)**
 
-To ensure only Administrator users can delete projects:
+Anyone with the **Owner** role, either at the project or group level, can
+delete a project. To allow only users with the Administrator role to delete projects:
 
-1. Check the **Default project deletion protection** checkbox.
-1. Click **Save changes**.
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. Scroll to **Default project deletion protection**, and select **Only admins can delete project**.
+1. Select **Save changes**.
 
 ## Default delayed project deletion **(PREMIUM SELF)**
 
@@ -104,7 +129,7 @@ To change this period:
 1. Select the desired option.
 1. Click **Save changes**.
 
-### Override default deletion delayed period
+### Override defaults and delete immediately
 
 Alternatively, projects that are marked for removal can be deleted immediately. To do so:
 
@@ -112,107 +137,132 @@ Alternatively, projects that are marked for removal can be deleted immediately.
 1. Delete the project as described in the
    [Administering Projects page](../../admin_area/#administering-projects).
 
-## Default project visibility
-
-To set the default visibility levels for new projects:
+## Configure project visibility defaults
 
-1. Select the desired default project visibility.
-1. Click **Save changes**.
+To set the default [visibility levels for new projects](../../../public_access/public_access.md):
 
-For more details on project visibility, see
-[Project visibility](../../../public_access/public_access.md).
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. Select the desired default project visibility:
+   - **Private** - Project access must be granted explicitly to each user. If this
+     project is part of a group, access will be granted to members of the group.
+   - **Internal** - The project can be accessed by any logged in user except external users.
+   - **Public** - The project can be accessed without any authentication.
+1. Select **Save changes**.
 
-## Default snippet visibility
+## Configure snippet visibility defaults
 
-To set the default visibility levels for new snippets:
+To set the default visibility levels for new [snippets](../../snippets.md):
 
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
 1. Select the desired default snippet visibility.
-1. Click **Save changes**.
+1. Select **Save changes**.
 
-For more details on snippet visibility, see
+For more details on snippet visibility, read
 [Project visibility](../../../public_access/public_access.md).
 
-## Default group visibility
+## Configure group visibility defaults
 
 To set the default visibility levels for new groups:
 
-1. Select the desired default group visibility.
-1. Click **Save changes**.
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. Select the desired default group visibility:
+   - **Private** - The group and its projects can only be viewed by members.
+   - **Internal** - The group and any internal projects can be viewed by any logged in user except external users.
+   - **Public** - The group and any public projects can be viewed without any authentication.
+1. Select **Save changes**.
 
 For more details on group visibility, see
 [Group visibility](../../group/index.md#group-visibility).
 
-## Restricted visibility levels
+## Restrict visibility levels
 
-To set the restricted visibility levels for projects, snippets, and selected pages:
+To restrict visibility levels for projects, snippets, and selected pages:
 
-1. Select the desired visibility levels to restrict.
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict.
 1. Select **Save changes**.
 
 For more details on project visibility, see
 [Project visibility](../../../public_access/public_access.md).
 
-## Import sources
-
-To specify from which hosting sites users can [import their projects](../../project/import/index.md):
-
-1. Check the checkbox beside the name of each hosting site.
-1. Click **Save changes**.
+## Configure allowed import sources
 
-## Project export
+You can specify from which hosting sites users can [import their projects](../../project/import/index.md):
 
-To enable project export:
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. Select each of **Import sources** to allow.
+1. Select **Save changes**.
 
-1. Check the **Project export enabled** checkbox.
-1. Click **Save changes**.
+## Enable project export
 
-For more details, see [Exporting a project and its data](../../../user/project/settings/import_export.md#exporting-a-project-and-its-data).
+To enable the export of
+[projects and their data](../../../user/project/settings/import_export.md#exporting-a-project-and-its-data):
 
-## Enabled Git access protocols
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. Select **Project export enabled**.
+1. Select **Save changes**.
 
-With GitLab access restrictions, you can select with which protocols users can communicate with
-GitLab.
+## Configure enabled Git access protocols
 
-Disabling an access protocol does not block access to the server itself by using those ports. The ports
-used for the protocol, SSH or HTTP(S), are still accessible. The GitLab restrictions apply at the
-application level.
+With GitLab access restrictions, you can select the protocols users can use to
+communicate with GitLab. Disabling an access protocol does not block port access to the
+server itself. The ports used for the protocol, SSH or HTTP(S), are still accessible.
+The GitLab restrictions apply at the application level.
 
 To specify the enabled Git access protocols:
 
-1. Select the desired Git access protocols from the dropdown:
+1. Sign in to GitLab as a user with [Administrator role](../../permissions.md).
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. In the left sidebar, select **Settings > General**.
+1. Expand the **Visibility and access controls** section.
+1. Select the desired Git access protocols:
    - Both SSH and HTTP(S)
    - Only SSH
    - Only HTTP(S)
-1. Click **Save changes**.
+1. Select **Save changes**.
 
 When both SSH and HTTP(S) are enabled, users can choose either protocol.
-
-When only one protocol is enabled:
+If only one protocol is enabled:
 
 - The project page shows only the allowed protocol's URL, with no option to
   change it.
-- A tooltip is shown when you hover over the URL's protocol, if an action
-  on the user's part is required. For example, adding an SSH key or setting a password.
+- GitLab shows a tooltip when you hover over the URL's protocol, if user action
+  (such as adding a SSH key or setting a password) is required:
 
-![Project URL with SSH only access](img/restricted_url.png)
+  ![Project URL with SSH only access](img/restricted_url.png)
 
-On top of these UI restrictions, GitLab denies all Git actions on the protocol
-not selected.
+GitLab only allows Git actions for the protocols you select.
 
 WARNING:
 GitLab versions [10.7 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18021),
 allow the HTTP(S) protocol for Git clone or fetch requests done by GitLab Runner
-from CI/CD jobs, even if **Only SSH** was selected.
+from CI/CD jobs, even if you select **Only SSH**.
 
-## Custom Git clone URL for HTTP(S)
+## Customize Git clone URL for HTTP(S)
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18422) in GitLab 12.4.
 
 You can customize project Git clone URLs for HTTP(S), which affects the clone
 panel:
 
-![Clone panel](img/clone_panel_v12_4.png)
-
 For example, if:
 
 - Your GitLab instance is at `https://example.com`, then project clone URLs are like
@@ -231,7 +281,7 @@ NOTE:
 SSH clone URLs can be customized in `gitlab.rb` by setting `gitlab_rails['gitlab_ssh_host']` and
 other related settings.
 
-## RSA, DSA, ECDSA, ED25519 SSH keys
+## Configure defaults for RSA, DSA, ECDSA, ED25519 SSH keys
 
 These options specify the permitted types and lengths for SSH keys.
 
@@ -242,7 +292,7 @@ To specify a restriction for each key type:
 
 For more details, see [SSH key restrictions](../../../security/ssh_keys_restrictions.md).
 
-## Allow mirrors to be set up for projects
+## Enable project mirroring
 
 This option is enabled by default. By disabling it, both
 [pull and push mirroring](../../project/repository/repository_mirroring.md) no longer

doc/user/group/index.md

@@ -37,7 +37,7 @@ Like projects, a group can be configured to limit the visibility of it to:
 - All signed-in users.
 - Only explicit group members.
 
-The restriction for [visibility levels](../admin_area/settings/visibility_and_access_controls.md#restricted-visibility-levels)
+The restriction for [visibility levels](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels)
 on the application setting level also applies to groups. If set to internal, the explore page is
 empty for anonymous users. The group page has a visibility level icon.
 
@@ -220,10 +220,10 @@ To change this setting for a specific group:
 1. Select the desired option in the **Default branch protection** dropdown list.
 1. Click **Save changes**.
 
-To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection).
+To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#protect-default-branches).
 
 NOTE:
-In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../admin_area/settings/visibility_and_access_controls.md#disable-group-owners-from-updating-default-branch-protection).
+In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../admin_area/settings/visibility_and_access_controls.md#prevent-overrides-of-default-branch-protection).
 
 ## Add projects to a group
 
@@ -248,7 +248,7 @@ To change this setting for a specific group:
 1. Select the desired option in the **Allowed to create projects** dropdown list.
 1. Click **Save changes**.
 
-To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#default-project-creation-protection).
+To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects).
 
 ## Group activity analytics **(PREMIUM)**
 

doc/user/permissions.md

@@ -330,7 +330,7 @@ The following table lists group permissions available for each role:
   Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup)
 1. Introduced in GitLab 12.2.
 1. Default project creation role can be changed at:
-   - The [instance level](admin_area/settings/visibility_and_access_controls.md#default-project-creation-protection).
+   - The [instance level](admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects).
    - The [group level](group/index.md#specify-who-can-add-projects-to-a-group).
 1. Does not apply to subgroups.
 1. Developers can push commits to the default branch of a new project only if the [default branch protection](group/index.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected".

doc/user/profile/index.md

@@ -86,7 +86,7 @@ not.
 
 When visiting the public page of a user, you can only see the projects which you have privileges to.
 
-If the [public level is restricted](../admin_area/settings/visibility_and_access_controls.md#restricted-visibility-levels),
+If the [public level is restricted](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels),
 user profiles are only visible to signed-in users.
 
 ## Add external accounts to your user profile page

doc/user/project/import/phabricator.md

@@ -36,4 +36,4 @@ of the project being imported into, then the user will be linked.
 
 ## Enable this feature
 
-Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin Area.
+Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) in the Admin Area.

doc/user/project/protected_branches.md

@@ -30,7 +30,7 @@ When a branch is protected, the default behavior enforces these restrictions on
 ### Set the default branch protection level
 
 Administrators can set a default branch protection level in the
-[Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection).
+[Admin Area](../admin_area/settings/visibility_and_access_controls.md#protect-default-branches).
 
 ## Configure a protected branch
 

doc/user/project/working_with_projects.md

@@ -22,7 +22,7 @@ projects with the largest number of comments in the past month, click **Trending
 
 NOTE:
 By default, `/explore` is visible to unauthenticated users. However, if the
-[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restricted-visibility-levels)
+[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels)
 is restricted, `/explore` is visible only to signed-in users.
 
 ## Create a project