Clarify expectations re: Mattermost notifications (#7378)

* Initial commit to build new info architecture outline

* Drafted web, desktop, & mobile notification details

* Channel-specific & reply-thread prod expectations

* Final notification section updates

* Final notifications updates

* Incorporated reviewer feedback

* Incorporated reviewer feedback

---------

Co-authored-by: M-ZubairAhmed <m-zubairahmed@protonmail.com>

source/about/mattermost-v9-changelog.md

@@ -160,7 +160,7 @@ See [this walkthrough video](https://mattermost.com/video/mattermost-v9-10-chang
  - Pre-packaged Mattermost Copilot plugin version [v0.8.1](https://github.com/mattermost/mattermost-plugin-ai/releases/tag/v0.8.1).
  - Pre-packaged Calls plugin version [v0.28.2](https://github.com/mattermost/mattermost-plugin-calls/releases/tag/v0.28.2).
  - Re-designed the user profile popover and improved its performance.
- - Added banner to prompt users to give desktop notification permissions when opening the app.
+ - Added banner to prompt users to allow notification permissions when opening the app in web browsers.
  - Increased the width of the profile picture setting to match other user settings.
  - Improved screen reader support for the emoji picker.
  - Improved the accessibility of plugin buttons in the channel header.

source/collaborate/message-priority.rst

@@ -42,7 +42,7 @@ To enable persistent notifications for a message:
 Receive persistent notifications
 --------------------------------
 
-You must have desktop and/or mobile push notifications enabled to receive persistent notifications. How you're notified depends on your :doc:`notifications preferences </preferences/manage-your-notifications>` for desktop and mobile push notifications. You won't be notified when your availability is set to **Do Not Disturb**, or if you're :ref:`Out of Office <preferences/set-your-status-availability:set your availability>`. Learn more about customizing how you receive notifications by visiting the :ref:`get notified <preferences/manage-your-notifications:get notified>` documentation.
+You must have desktop and/or mobile push notifications enabled to receive persistent notifications. How you're notified depends on your :doc:`notifications preferences </preferences/manage-your-notifications>` for desktop and mobile push notifications. You won't be notified when your availability is set to **Do Not Disturb**, or if you're :ref:`Out of Office <preferences/set-your-status-availability:set your availability>`. Learn more about managing and customizing how you receive :doc:`Mattermost notifications </preferences/manage-your-notifications>`.
 
 Urgent messages show a red mention badge which remains visibible until you view the message. Selecting the **Acknowledge** icon (when present) won't impact the urgent red mention badge.
 

source/preferences/manage-your-channel-specific-notifications.rst

@@ -0,0 +1,73 @@
+Manage your channel-specific notifications
+===========================================
+
+.. include:: ../_static/badges/allplans-cloud-selfhosted.rst
+  :start-after: :nosearch:
+
+By default, your web and desktop notification preferences apply to all channels you’re a member of. You can customize your per-channel notification preferences for any channel you're a member of for the following actions:
+
+- `Mute channels <#mute-channels>`__
+- `Ignore channel-wide @mentions <#ignore-channel-wide-@mentions>`__
+- `Auto-follow all new threads <#auto-follow-all-new-channel-threads>`__
+
+.. tab:: Web/Desktop
+
+  You have 2 ways to manage notification preferences per channel:
+
+  1. Select the channel name, then select **Notification Preferences** from the drop-down list.
+
+  .. image:: ../images/channel-notification-settings.gif
+    :alt: Select the channel name dropdown to access channel-specific notification preferences.
+
+  2. Alternatively, select the channel's **View Info** |channel-info| icon, and then select **Notification Preferences** in the right pane.
+
+.. tab:: Mobile
+
+  Tap the channel name, and then tap **Mobile Notifications**.
+
+Mute channels
+-------------
+
+All channels are unmuted by default, including direct and group messages, as well as private and public channels. 
+
+You can choose to mute or unmute a channel at any time as follows:
+
+- Select **Mute Conversation** or **Unmute Conversation** for direct and group messages.
+- Select **Mute Channel** or **Unmute Channel** for private and public channels.
+
+Once a channel is muted:
+
+- All notifications for that channel are disabled, including email, desktop, incoming call ring tones, and push notifications.
+- The muted channel displays a mute icon next to the channel name.
+- The channel is greyed out in the channel sidebar, and doesn't appear bold to indicate unread messages unless you’re :doc:`@mentioned </collaborate/mention-people>` in that channel directly.
+
+Ignore channel-wide @mentions
+------------------------------
+
+By default, you're notified every time someone uses channel-wide :doc:`@mentions </collaborate/mention-people>` including :ref:`@channel and @all <collaborate/mention-people:@channel and @all>`, as well as :ref:`@here <collaborate/mention-people:@here>`.
+
+When you choose to ignore channel-wide @mentions in channels, the channel name is bolded in the channel sidebar for new unreads unless it's muted.
+
+Follow all new channel threads
+-------------------------------
+
+By default, you don’t automatically follow new conversation threads in any channel unless you start a thread or reply to a thread, follow a thread, or are @mentioned in a thread.
+
+You can configure Mattermost to automatically follow every thread in a channel.
+
+.. tab:: Web/Desktop
+
+  1. Select the channel name to access more channel options.
+  2. Select **Notification Preferences**.
+  3. Under **Follow all threads in this channel**, select **Automatically follow threads in this channel**.
+  4. Select **Save**.
+
+  Select **Threads** in the channel sidebar to access all threads you're following, and to unfollow threads you no longer want to follow.
+
+.. tab:: Mobile
+
+  1. In a channel, tap the **More** icon |more-icon| to the right of the channel name.
+  2. Tap **View info**.
+  3. Tap **Follow all threads**.
+
+  Tap **Threads** in the channel list to access all threads you're following, and to unfollow threads you no longer want to follow.

source/preferences/manage-your-desktop-notifications.rst

@@ -0,0 +1,91 @@
+Manage your desktop notifications
+=================================
+
+.. include:: ../_static/badges/allplans-cloud-selfhosted.rst
+  :start-after: :nosearch:
+
+.. |dot-badge| image:: ../images/dot-badge.png
+  :alt: A dot on the badge means you have unread activity in at least one channel you're a member of.
+  :width: 50px
+
+.. |numbered-badge| image:: ../images/numbered-badge.png
+  :alt: A numbered badge means you have at least 1 unread message, @mention, or one of your keywords has triggered a notification.
+  :width: 50px
+
+Enable notifications
+--------------------
+
+From Mattermost v9.9 and desktop app v5.5, Mattermost prompts you to enable notifications in the desktop app the first time you connect to a Mattermost server.
+
+- When you select **Allow**, you won't be asked again. You'll start receiving notifications in the desktop app for all Mattermost activity with `badges <#badge-based-notifications>`__, `banner alerts <#banner-alerts>`__ and `sounds <#notification-sounds>`__. See the section below on `customizing your notifications <#customize-your-notifications>`__ based on how you prefer to be notified about Mattermost activity in the desktop app.
+- If you select **Deny** or **Deny Permanently**, you won't be asked again. You won't receive Mattermost notifications in the web browser. You can change this preference by :ref:`editing the server connection <preferences/connect-multiple-workspaces:edit a server>` to :ref:`manage your notification permissions <preferences/connect-multiple-workspaces:manage system permissions>`.
+
+.. note::
+
+  - You may also need to enable notifications in Windows, macOS, or Linux for Mattermost by changing your System Preferences.
+  - When you allow desktop notifications, you'll also receive a second prompt asking you to allow notifications in your default web browser.
+
+    .. image:: ../images/web-notification-prompt.png
+      :alt: An example of a Firefox web browser notification prompt.
+      :scale: 70
+
+Badge-based notifications
+-------------------------
+
+Mattermost desktop app icons display the following types of badges:
+
+- A numbered badge for unread :ref:`direct <collaborate/channel-types:direct messages>` :ref:`group <collaborate/channel-types:group messages>` messages, :doc:`@mentions </preferences/manage-your-mentions-keywords-notifications>`, and :doc:`keywords </preferences/manage-your-mentions-keywords-notifications>` you're actively watching. |numbered-badge|
+- A dot badge for unread activity. |dot-badge|
+
+Banner alerts
+-------------
+
+Banner alerts in the desktop app are popup windows that display for a limited time in the top right corner of your screen that summarizes the new activity.
+
+Notification sounds
+--------------------
+
+By default, desktop app notifications include audible sounds.
+
+Customize your notifications
+----------------------------
+
+By default, you are notified when you're @mentioned, when you receive a direct or group message, or for matches to keywords you're following. 
+
+Want to receive notifications about replies to threads you’re following? Select **Notify me about replies to threads I’m following**.
+
+Want notifications for all new messages? Select **Desktop and mobile notifications > All new messages**
+
+Desktop app users can also :doc:`customize their desktop app experience </preferences/customize-desktop-app-experience>` further based on their platform operating system.
+
+Change or disable sounds
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can change or disable notification sounds by going to **Desktop notification sounds > Message notification sound**.
+
+Incoming Call notifications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Want to hear a sound when a Mattermost call starts? If your Mattermost admin :ref:`enables this Beta feature <configure/plugins-configuration-settings:enable call ringing>`, you can choose the sound that plays when a call is started within a direct or group message by going to **Desktop notification sounds > Incoming call sound**.
+
+Disable all desktop notifications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Select **Desktop and mobile notifications > Nothing** to disable all desktop and :doc:`web notifications </preferences/manage-your-web-notifications>`.
+
+Clear the **Use different settings for my mobile devices** to additionally disable all Mattermost mobile notifications everywhere you use Mattermost.
+
+Additionally, macOS users can disable notifications for all unread activity in the desktop app by :doc:`customizing your desktop app experience </preferences/customize-desktop-app-experience>` to disable the **Show red badge on Dock icon to indicate unread messages** option.
+
+Frequently asked questions
+---------------------------
+
+What does a Mattermost icon with an exclamation point mean?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/server-logout-indicator.png
+  :alt: A Mattermost logo with an exclamation point means you're logged out of at least 1 Mattermost server you connect to using the desktop app.
+
+A Mattermost icon with an exclamation point means that you're logged out of at least 1 Mattermost server you connect to using the desktop app. Log back in to any servers as needed. See the :doc:`Connect to multiple workspaces </preferences/connect-multiple-workspaces>` documentation for details.
+
+If the icon continues to display, refresh the **Playbooks** and/or **Boards** tabs located at the top of the desktop app window.

source/preferences/manage-your-mentions-keywords-notifications.rst

@@ -0,0 +1,38 @@
+Manage your @mention and keyword notifications
+==============================================
+
+.. include:: ../_static/badges/allplans-cloud-selfhosted.rst
+  :start-after: :nosearch:
+
+You're :doc:`notified </preferences/manage-your-notifications>` in a :doc:`web browser </preferences/manage-your-web-notifications>`, the :doc:`desktop app </preferences/manage-your-desktop-notifications>`, and on your :doc:`mobile device </preferences/manage-your-mobile-notifications>`, when you're @mentioned by your username or first name, @mentioned as part of a user group, and for matches to keywords you're following.
+
+You're also notified when someone uses channel-wide :doc:`@mentions </collaborate/mention-people>` including :ref:`@channel and @all <collaborate/mention-people:@channel and @all>`, as well as :ref:`@here <collaborate/mention-people:@here>`.
+
+For all other messages, channels appear bolded to indicate unread activity.
+
+Customize notification keywords
+--------------------------------
+
+Using a web browser or the desktop app, you can customize keywords to trigger notifications. Keywords aren't case-sensitive.
+
+For example, you can receive notifications for all messages and threads related to a specific topic, project name, or customer.
+
+.. image:: ../images/keywords-trigger-mentions.gif
+  :alt: A walkthrough of setting keywords that trigger mentions in Mattermost.
+
+.. tip::
+
+  Separate multiple keywords using commas or by pressing :kbd:`Tab`, and use :kbd:`Backspace` to manage keywords.
+
+Passively track keywords (no notification)
+------------------------------------------
+
+.. include:: ../_static/badges/ent-pro-only.rst
+  :start-after: :nosearch:
+
+From Mattermost v9.3, Mattermost Enterprise and Professional customers interested calling attention to specific topics of interest across channels can do so without sending notifications to a Mattermost client.
+
+Using a web browser or the desktop app, you can passively track key terms by specifying single or multiple words to be highlighted in all channels you're a member of. Keywords and phrases are automatically highlighted using a color based on your :doc:`Mattermost theme </preferences/customize-your-theme>`.
+
+.. image:: ../images/keywords-highlighted.gif
+  :alt: A walkthrough of setting keywords that are highlighted in Mattermost.

source/preferences/manage-your-mobile-notifications.rst

@@ -0,0 +1,97 @@
+Manage your mobile notifications
+=================================
+
+.. include:: ../_static/badges/allplans-cloud-selfhosted.rst
+  :start-after: :nosearch:
+
+.. |numbered-badge| image:: ../images/numbered-badge.png
+  :alt: A numbered badge means you have at least 1 unread message, @mention, or one of your keywords has triggered a notification.
+  :width: 50px
+
+Enable notifications
+--------------------
+
+From Mattermost v9.9, Mattermost prompts you to enable notifications in the mobile app the first time you open the app.
+
+When you enable notifications, you'll start receiving notifications for all Mattermost activity with `badges <#badge-based-notifications>`__, and `push notifications <#push-notifications>`__. See the section below on `customizing your notifications <#customize-your-notifications>`__ based on how you prefer to be notified about Mattermost activity on your mobile device.
+
+.. note::
+
+  You may also need to enable notifications in iOS or Android for Mattermost by changing your device preferences.
+
+Badge-based notifications
+-------------------------
+
+Mattermost mobile app icons display numbered badges for unread :ref:`direct <collaborate/channel-types:direct messages>` and :ref:`group <collaborate/channel-types:group messages>` messages, and :doc:`@mentions </preferences/manage-your-mentions-keywords-notifications>`, :doc:`keywords </preferences/manage-your-mentions-keywords-notifications>` you're actively watching.
+
+|numbered-badge|
+
+.. note::
+
+  - The Mattermost mobile app doesn't display dot badges indicating other unread activity by design. The activity you're directly involved in is prioritized over other activity.
+  - Android users may see Mattermost notifications in the Android Notification Shade while the Mattermost icon shows no badge. This is because the Android notification system may also display badges unread activity.
+
+Push notifications
+------------------
+
+You'll see mobile push notification messages on your device as follows:
+
+- **iOS**: On the Lock Screen, Notification Center, and as Banners/Alerts based on your iOS settings.
+- **Android**: On the Lock Screen, Notification Shade, and as Banners/Heads-Up Notifications based on your Android settings.
+
+Customize your notifications
+----------------------------
+
+You can manage your mobile notifications in both the desktop app and the mobile app.
+
+Desktop app
+~~~~~~~~~~~~
+
+In the desktop app, manage your mobile notification preferences by selecting the **Settings** |gear| icon located in the top right corner of the screen, and select **Notifications > Desktop and mobile notifications**.
+
+By default, you receive mobile notifications when your Mattermost availability is :ref:`away or offline <preferences/set-your-status-availability:set your availability>`.
+
+- Want to receive mobile notifications when you're online too? Under **Trigger mobile notifications when I am**, select **Online, away, or offline**. Note that you won't be notified on your device if you're actively using Mattermost in a web browser. Alternatively, select **Offline** to receive fewer mobile notifications.
+
+- Want different desktop and mobile notifications? Select **Use different settings for my mobile devices**, and then select **All new messages**, or **Mentions, direct messages and group messages**.
+
+Mobile app
+~~~~~~~~~~
+
+In the mobile app, tap your profile picture, then tap **Settings > Notifications**.
+
+- Tap **Mentions** to disable notifications based on keywords that trigger mentions, including first name, username, channel-wide @mentions, and keywords you've specified.
+- Tap **Push Notifications** to choose what to be notified about.
+
+You can also :ref:`manage email notifications <preferences/manage-your-notifications:email notifications>` and :ref:`send automatic replies to direct messages <preferences/manage-your-thread-reply-notifications:send automatic replies to direct messages>` directly from your device.
+
+Incoming Call notifications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Want to hear a sound on your mobile device when a Mattermost call starts? If your Mattermost admin :ref:`enables this Beta feature <configure/plugins-configuration-settings:enable call ringing>`, select **Call Notifications** to choose the sound that plays when a call is started within a direct or group message you're participating in.
+
+.. tip::
+
+  - From Mattermost mobile app v2.19, incoming call sounds also include device vibration, as well as vibration-only when your device is in silent mode.
+  - If you prefer a separate call sound on mobile, your mobile change applies only to your mobile device.
+
+Disable all mobile notifications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To disable all Mattermost mobile notifications, tap **Push Notifications > Nothing**.
+
+Frequently asked questions
+--------------------------
+
+Are mobile notification counts the same as other Mattermost clients?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+No. You're only notified of unread threads with @mentions on your mobile device. You're not notified of general unread activity on mobile.
+
+What does a Mattermost icon with an exclamation point mean?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../images/server-logout-indicator.png
+  :alt: A Mattermost logo with an exclamation point means you're logged out of at least 1 Mattermost server you connect to using the mobile app.
+
+A Mattermost icon with an exclamation point means that you're logged out of at least 1 Mattermost server you connect to using the mobile app. Log back in to any servers as needed. See the :doc:`Connect to multiple workspaces </preferences/connect-multiple-workspaces>` documentation for details.