Merge branch 'msj-notifications-okr' into 'master'

Edit Notifications doc for reading level

See merge request gitlab-org/gitlab!68075

doc/user/profile/notifications.md

@@ -5,41 +5,44 @@ group: Project Management
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# GitLab Notification Emails **(FREE)**
+# Notification emails **(FREE)**
 
-GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications
-enabled, you can receive updates about activity in issues, merge requests, epics, and designs.
-Notifications are sent via email.
+Stay informed about what's happening in GitLab with email notifications.
+You can receive updates about activity in issues, merge requests, epics, and designs.
 
-For the tool that enables GitLab administrators to send messages to users, read
+For the tool that GitLab administrators can use to send messages to users, read
 [Email from GitLab](../../tools/email.md).
 
-## Receiving notifications
+## Receive notifications
 
 You receive notifications for one of the following reasons:
 
-- You participate in an issue, merge request, epic, or design. In this context, _participate_ means comment, or edit.
-- You [enable notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics).
+- You participate in an issue, merge request, epic, or design. In this context, _participate_ means
+  comment or edit.
+- You've [enabled notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics).
 - You configured notifications at the [project](#project-notifications) and/or [group](#group-notifications) level.
 
 While notifications are enabled, you receive notification of actions occurring in that issue, merge request, or epic.
 
 NOTE:
-Notifications can be blocked by an administrator, preventing them from being sent.
+Administrators can block notifications, preventing them from being sent.
 
-## Tuning your notifications
+## Tune your notifications
 
-The number of notifications can be overwhelming. GitLab allows you to tune the notifications you receive.
+Getting many notifications can be overwhelming. You can tune the notifications you receive.
 For example, you might want to be notified about all activity in a specific project.
-For other projects, you only need to be notified when you are mentioned by name.
+For other projects, you only want to be notified when you are mentioned by name.
 
-You can tune the notifications you receive by combining your notification settings:
+You can tune the notifications you receive by changing your notification settings:
 
 - [Global notification settings](#global-notification-settings)
 - [Notification scope](#notification-scope)
 - [Notification levels](#notification-levels)
 
-## Editing notification settings
+## Edit notification settings
+
+These notification settings apply only to you. They do not affect the notifications received by
+anyone else in the same project or group.
 
 To edit your notification settings:
 
@@ -48,9 +51,20 @@ To edit your notification settings:
 1. In the left sidebar, select **Notifications**.
 1. Edit the desired notification settings. Edited settings are automatically saved and enabled.
 
-These notification settings apply only to you. They do not affect the notifications received by anyone else in the same project or group.
+## Notification scope
+
+You can tune the scope of your notifications by selecting different notification levels for each project and group.
 
-## Global notification settings
+Notification scope is applied from the broadest to most specific levels:
+
+- **Global (default)**: Your global, or _default_, notification level applies if you
+  have not selected a notification level for the project or group in which the activity occurred.
+- **Group**: For each group, you can select a notification level. Your group setting
+  overrides your default setting.
+- **Project**: For each project, you can select a notification level. Your project
+  setting overrides the group setting.
+
+### Global notification settings
 
 Your **Global notification settings** are the default settings unless you select
 different values for a project or a group.
@@ -65,95 +79,78 @@ different values for a project or a group.
 
 ![notification settings](img/notification_global_settings_v13_12.png)
 
-### Notification scope
-
-You can tune the scope of your notifications by selecting different notification levels for each project and group.
-
-Notification scope is applied in order of precedence (highest to lowest):
-
-- **Project**: For each project, you can select a notification level. Your project
-  setting overrides the group setting.
-- **Group**: For each group, you can select a notification level. Your group setting
-  overrides your default setting.
-- **Global (default)**: Your global, or _default_, notification level applies if you
-  have not selected a notification level for the project or group in which the activity occurred.
-
-#### Project notifications
+### Group notifications
 
-You can select a notification level for each project to help you closely monitor activity in select projects.
+You can select a notification level and email address for each group.
 
-![notification settings](img/notification_project_settings_v12_8.png)
+#### Group notification level
 
-To select a notification level for a project, use either of these methods:
+To select a notification level for a group, use either of these methods:
 
 1. In the top-right corner, select your avatar.
 1. Select **Preferences**.
 1. In the left sidebar, select **Notifications**.
-1. Locate the project in the **Projects** section.
+1. Locate the project in the **Groups** section.
 1. Select the desired [notification level](#notification-levels).
 
 Or:
 
-1. Go to your project.
-1. Select the notification dropdown, marked with a bell icon (**{notifications}**).
+1. On the top bar, select **Menu > Groups** and find your group.
+1. Select the notification dropdown, next to the bell icon (**{notifications}**).
 1. Select the desired [notification level](#notification-levels).
 
-<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
-For a demonstration of how to be notified when a new release is available, see [Notification for releases](https://www.youtube.com/watch?v=qyeNkGgqmH4).
+#### Group notification email address
 
-#### Group notifications
-
-You can select a notification level and email address for each group.
-
-![notification settings](img/notification_group_settings_v12_8.png)
-
-##### Group notification level
+> Introduced in GitLab 12.0
 
-To select a notification level for a group, use either of these methods:
+You can select an email address to receive notifications for each group you belong to. This could be useful, for example, if you work freelance, and want to keep email about clients' projects separate.
 
 1. In the top-right corner, select your avatar.
 1. Select **Preferences**.
 1. In the left sidebar, select **Notifications**.
 1. Locate the project in the **Groups** section.
-1. Select the desired [notification level](#notification-levels).
-
----
-
-1. Go to your group.
-1. Select the notification dropdown, marked with a bell icon (**{notifications}**).
-1. Select the desired [notification level](#notification-levels).
+1. Select the desired email address.
 
-##### Group notification email address
+### Project notifications
 
-> Introduced in GitLab 12.0
+You can select a notification level for each project to help you closely monitor activity in select projects.
 
-You can select an email address to receive notifications for each group you belong to. This could be useful, for example, if you work freelance, and want to keep email about clients' projects separate.
+To select a notification level for a project, use either of these methods:
 
 1. In the top-right corner, select your avatar.
 1. Select **Preferences**.
 1. In the left sidebar, select **Notifications**.
-1. Locate the project in the **Groups** section.
-1. Select the desired email address.
+1. Locate the project in the **Projects** section.
+1. Select the desired [notification level](#notification-levels).
+
+Or:
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. Select the notification dropdown, next to the bell icon (**{notifications}**).
+1. Select the desired [notification level](#notification-levels).
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+To learn how to be notified when a new release is available, see [Notification for releases](https://www.youtube.com/watch?v=qyeNkGgqmH4).
 
 ### Notification levels
 
 For each project and group you can select one of the following levels:
 
-| Level       | Description |
-|:------------|:------------|
-| Global      | Your global settings apply. |
-| Watch       | Receive notifications for any activity. |
+| Level       | Description                                                 |
+| ----------- | ----------------------------------------------------------- |
+| Global      | Your global settings apply.                                 |
+| Watch       | Receive notifications for any activity.                     |
 | On mention  | Receive notifications when [mentioned](../project/issues/issue_data_and_actions.md#mentions) in a comment. |
 | Participate | Receive notifications for threads you have participated in. |
-| Disabled    | Turns off notifications. |
-| Custom      | Receive notifications for custom selected events. |
+| Disabled    | Turns off notifications.                                    |
+| Custom      | Receive notifications for custom selected events.           |
 
 ### Product marketing emails
 
 You can receive emails that teach you about various GitLab features.
 This is enabled by default.
 
-To opt out, [edit your notification settings](#editing-notification-settings) and clear the
+To opt out, [edit your notification settings](#edit-notification-settings) and clear the
 **Receive product marketing emails** checkbox.
 
 Disabling these emails does not disable all emails.
@@ -173,51 +170,56 @@ for all users.
 
 Users are notified of the following events:
 
+<!-- The table is sorted first by recipient, then alphabetically. -->
+
 | Event                        | Sent to             | Settings level               |
 |------------------------------|---------------------|------------------------------|
-| New SSH key added            | User                | Security email, always sent. |
-| SSH key has expired          | User                | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12 |
-| New email added              | User                | Security email, always sent. |
+| New release                  | Project members     | Custom notification          |
+| Project moved                | Project members (1) | (1) not disabled             |
 | Email changed                | User                | Security email, always sent. |
+| Group access level changed   | User                | Sent when user group access level is changed |
+| New email added              | User                | Security email, always sent. |
+| New SAML/SCIM user provisioned | User              | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 |
+| New SSH key added            | User                | Security email, always sent. |
+| New user created             | User                | Sent on user creation, except for OmniAuth (LDAP)|
 | Password changed             | User                | Security email, always sent when user changes their own password |
 | Password changed by administrator | User           | Security email, always sent when an administrator changes the password of another user |
-| Two-factor authentication disabled | User          | Security email, always sent. |
-| New user created             | User                | Sent on user creation, except for OmniAuth (LDAP)|
-| New SAML/SCIM user provisioned | User            | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 |
-| User added to project        | User                | Sent when user is added to project |
+| Personal access tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User          | Security email, always sent. |
+| Personal access tokens have expired | User         | Security email, always sent. |
 | Project access level changed | User                | Sent when user project access level is changed |
+| SSH key has expired          | User                | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12 |
+| Two-factor authentication disabled | User          | Security email, always sent. |
 | User added to group          | User                | Sent when user is added to group |
-| Group access level changed   | User                | Sent when user group access level is changed |
-| Personal Access Tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User          | Security email, always sent. |
-| Personal Access Tokens have expired | User         | Security email, always sent. |
-| Project moved                | Project members (1) | (1) not disabled             |
-| New release                  | Project members     | Custom notification          |
+| User added to project        | User                | Sent when user is added to project |
 
 ## Notifications on issues, merge requests, and epics
 
-To enable notifications on one specific issue, merge request or epic, you need to enable the **Notifications** toggle in the right sidebar.
+To enable notifications on a specific issue, merge request, or epic, you must turn on the
+**Notifications** toggle in the right sidebar.
 
-- **Enable**: If you are not a participant in the discussion on that issue, but
-  want to receive notifications on each update, subscribe to it.
-- **Disable**: If you are receiving notifications for updates to that issue but no
-  longer want to receive them, unsubscribe from it.
+- To subscribe, **turn on** if you are not a participant in the discussion, but want to receive
+  notifications on each update.
+- To unsubscribe, **turn off** if you are receiving notifications for updates but no longer want to
+  receive them, unsubscribe from it.
 
-Disabling this toggle only unsubscribes you from updates related to this issue, merge request, or epic.
+Turning this toggle off only unsubscribes you from updates related to this issue, merge request, or epic.
 Learn how to [opt out of all emails from GitLab](#opt-out-of-all-gitlab-emails).
 
-Enabling this notification on an epic doesn't automatically subscribe you to the issues linked
+Turning notifications on in an epic doesn't automatically subscribe you to the issues linked
 to the epic.
 
 For most events, the notification is sent to:
 
 - Participants:
   - The author and assignee of the issue/merge request.
-  - Authors of comments on the issue/merge request.
-  - Anyone mentioned by `@username` in the title or description of the issue, merge request or epic.
-  - Anyone with notification level "Participating" or higher that is mentioned by `@username` in any of the comments on the issue, merge request, or epic.
+  - Authors of comments.
+  - Anyone [mentioned](../project/issues/issue_data_and_actions.md#mentions) by username in the title
+    or description of the issue, merge request or epic.
+  - Anyone with notification level "Participating" or higher that is mentioned by their username in
+    any of the comments on the issue, merge request, or epic.
 - Watchers: users with notification level "Watch".
 - Subscribers: anyone who manually subscribed to the issue, merge request, or epic.
-- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below.
+- Custom: Users with notification level "custom" who turned on notifications for any of the events in the following table.
 
 NOTE:
 To minimize the number of notifications that do not require any action, in
@@ -259,16 +261,17 @@ If the title or description of an issue or merge request is
 changed, notifications are sent to any **new** mentions by `@username` as
 if they had been mentioned in the original text.
 
-You don't receive notifications for issues, merge requests or milestones created
-by yourself (except when an issue is due). You only receive automatic
-notifications when somebody else comments or adds changes to the ones that
-you've created or mentions you.
+BNy default, you don't receive notifications for issues, merge requests, or epics created
+by yourself. You only receive notifications when somebody else comments or adds changes to the ones
+that you've created or mentions you, or when an issue is due soon.
+To always receive notifications on your own issues and so on, you must turn on
+[notifications about your own activity](#global-notification-settings).
 
 If an open merge request becomes unmergeable due to conflict, its author is notified about the cause.
-If a user has also set the merge request to automatically merge once pipeline succeeds,
+If a user has also set the merge request to automatically merge when pipeline succeeds,
 then that user is also notified.
 
-## Design email notifications
+## Notifications on designs
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217095) in GitLab 13.6.
 
@@ -284,7 +287,7 @@ The participants are:
 
 If you no longer wish to receive any email notifications:
 
-1. [Go to the Notifications settings page.](#editing-notification-settings)
+1. [Go to the Notifications settings page.](#edit-notification-settings)
 1. Clear the **Receive product marketing emails** checkbox.
 1. Set your **Global notification level** to **Disabled**.
 1. Clear the **Receive notifications about your own activity** checkbox.
@@ -295,7 +298,7 @@ On self-managed installations, even after doing this, your instance administrato
 [can still email you](../../tools/email.md).
 To unsubscribe, select the unsubscribe link in one of these emails.
 
-## Filtering email
+## Filter email
 
 Notification email messages include GitLab-specific headers. You can filter the notification emails based on the content of these headers to better manage your notifications. For example, you could filter all emails for a specific project where you are being assigned either a merge request or issue.
 

doc/user/project/settings/index.md

@@ -247,7 +247,7 @@ setting **Enable CVE ID requests in the issue sidebar**.
 
 #### Disabling email notifications
 
-Project owners can disable all [email notifications](../../profile/notifications.md#gitlab-notification-emails)
+Project owners can disable all [email notifications](../../profile/notifications.md)
 related to the project by selecting the **Disable email notifications** checkbox.
 
 ### Merge request settings