Merge pull request #13114 from nextcloud/fix/noid/chat-documentation

fix(user): Enhance talk user documentation for calls

Author: rakekniven

user_manual/talk/breakout_rooms.rst

@@ -1,3 +1,5 @@
+.. _breakout-rooms:
+
 Breakout rooms
 ==============
 

user_manual/talk/call.rst

@@ -2,67 +2,176 @@
 Joining a call
 ================
 
-When you're in a conversation, you can start a call any time with the ``Start call`` button. Other participants will get notified and can join the call.
+Starting or joining a call
+---------------------------
 
-.. image:: images/device-settings-before-call.png
-    :width: 600px
+Browser and Talk Desktop client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If somebody else has started a call already, the button will change in a green ``Join call`` button.
+When you are part of a conversation and have permission to do so, you can start a call at any time by clicking ``Start call`` in the top bar.
+When a call is already in progress, join it by clicking the green ``Join call`` button in the chat area or the top bar.
 
 .. image:: images/join-call.png
     :width: 600px
 
-During a call, you can mute your microphone and disable your video with the buttons on the right side of the top bar, or using the shortcuts ``M`` to mute audio and ``V`` to disable video. You can also use the space bar to toggle mute. When you are muted, pressing space will unmute you so you can speak until you let go of the space bar. If you are unmuted, pressing space will mute you until you let go.
+.. note:: If you have not yet given permission to the browser or the Talk Desktop client to use your microphone and camera,
+    you will be prompted to do so when you click ``Start call`` or ``Join call``.
+    Choose the microphone and camera you would like to use and click ``Allow`` to grant access to your devices.
 
-You can hide your video (useful during a screen share) with the little arrow just above the video stream. Bring it back with the little arrow again.
+You will see ``Media settings``, where you can customise your call experience:
 
-You can access your settings and choose a different webcam, microphone and other settings in the ``...`` menu in the top bar.
+.. image:: images/calls/media-settings-initial.png
+    :width: 600px
 
-.. image:: images/media-settings.png
-    :width: 300px
+Controlling audio and video
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the microphone and camera icons at the bottom of the video preview to mute or unmute your microphone and enable or disable your camera before joining.
+
+.. note:: If one or both of your icons are greyed out, you either do not have a microphone or camera installed, or you did not give permission to the browser or Talk Desktop
+    client to use your microphone or camera. Check that you have granted permission to the browser or Talk Desktop client, and make sure your microphone and camera are not
+    in use by another application.
+
+Device settings allow you to choose which microphone and camera you want to use. This is useful if you have more than one microphone or camera available:
+
+.. image:: images/calls/media-settings-devices.png
+    :width: 400px
+
+Backgrounds
+^^^^^^^^^^^
+
+Backgrounds let you replace your video background with one of the predefined images.
+You can also upload your own image or choose one already in Nextcloud Files.
+Alternatively, choose the ``blur`` option to blur your live video background.
+
+.. image:: images/calls/media-settings-backgrounds.png
+    :width: 400px
+
+Immediately join a call
+^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to skip ``Media settings`` in the future, toggle the ``Skip device preview before joining a call`` switch in app settings.
+For future calls in this conversation, you will join directly, skipping the preview dialog.
+
+Record a call
+^^^^^^^^^^^^^
+
+If you started the call and wish to record it, check the ``Start recording immediately with the call`` checkbox.
+The call recording option might not be available to you, depending on whether your system administrators have enabled this option
+and whether you have ``Moderator`` permission for the conversation.
+If you are joining and the call is being recorded, you might be required to consent before being allowed to join.
+For more information, see :ref:`Call recording <call-recording>`.
+
+Start the call
+^^^^^^^^^^^^^^
+
+Click the ``Start call`` button at the bottom of ``Media settings`` to notify all conversation participants of the call.
+If you do not want to notify the other participants, start a silent call by opening the three-dot menu to the left of the ``Start call`` button
+and choosing ``Call without notification``.
+
+.. image:: images/calls/media-settings-silent-call.png
+    :width: 400px
+
+.. image:: images/calls/media-settings-silent-call-2.png
+    :width: 400px
 
-From the media settings dialog, you can also change the background of your video.
+.. note:: Other participants can modify notifications on a per-conversation level, including whether they want to receive call notifications.
 
-.. image:: images/background-settings-in-call.png
-    :width: 500px
+Your user status will be set to ``In a call`` and your user status icon will display the speech bubble emoji.
 
-All these settings are also available as direct actions in the bottom bar.
+Mobile clients
+~~~~~~~~~~~~~~
 
-.. image:: images/call-bottom-bar.png
+When you are part of a conversation and have permission to do so, you can start a call at any time by
+tapping the ``Phone`` or ``Video`` icon in the top bar.
+The ``Phone`` icon starts a voice-only call; the ``Video`` icon starts a video call.
+
+A voice call uses the device microphone and earpiece, like a regular phone call.
+A video call uses the loudspeaker in hands-free mode and enables your front-facing camera by default; you can disable it at any time.
+
+If someone else starts a call, you may receive a notification and your device may ring or vibrate,
+depending on your notification settings.
+Tap ``Phone`` or ``Video`` to join, or tap the red button to decline. Declining dismisses the call notification on that device.
+
+You can control your microphone and camera (if in a video call) with the options shown at the bottom of the screen.
+
+Your user status will be set to ``In a call`` and your user status icon will display a speech bubble.
+
+During a call
+--------------
+
+After you join a call, you will see the call view. It shows the video feeds of all participants currently in the call, with additional information and controls.
+
+.. image:: images/calls/during-a-call-details.png
+    :width: 400px
+
+The leftmost element shows the elapsed call time.
+
+Next to it, you will see the number of participants that have joined the current call.
+Clicking the number opens the right sidebar and shows the list of participants.
+Participants that have joined the call will be listed first.
+
+You will also see each participant's talking time if they have spoken during the call:
+
+.. image:: images/calls/participant-talk-time.png
+    :width: 400px
+
+You can access additional call options and settings from the three-dot menu in the top bar.
+
+.. image:: images/media-settings.png
     :width: 300px
 
-You can change other settings in the ``Talk settings`` dialog.
+Set up breakout rooms
+~~~~~~~~~~~~~~~~~~~~~
 
-.. image:: images/talk-settings.png
-    :width: 600px
+Breakout rooms allow you to divide a call into smaller groups for more focused discussions.
+Depending on your permissions and how your instance is configured, this option may not be available to you.
+For more information, see :ref:`Breakout rooms <breakout-rooms>`.
 
 Download call participants list
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can download the list of participants in a call from the ``...`` menu in the top bar. This will download a CSV file with the names and email addresses of all participants in the call.
+You can download the list of participants in a call from the three-dot menu in the top bar. This downloads a CSV file with the names and email addresses of all participants.
 
 .. image:: images/download-participants-list.png
    :width: 400px
 
-The table in the CSV file contains the following columns:
+The CSV file contains the following columns:
 
 - **Name**: The name of the participant.
 - **Email**: The email address of the participant.
 - **Type**: Indicates whether the participant is a registered user or a guest.
 - **Identifier**: Unique identifier for the participant.
 
+Controlling audio and video
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Bottom bar of the call view offers media controls, layout settings and other features you can use during a call.
 
+.. image:: images/calls/during-a-call-controls.png
+    :width: 400px
 
+Use the microphone and camera icons to mute/unmute your microphone and enable/disable your camera.
+You can also use the keyboard shortcuts ``M`` to mute/unmute your microphone and ``V`` to enable/disable your camera.
+Use the space bar to push-to-talk: when you are muted, pressing space will unmute you until you let go; when you are unmuted, pressing space will mute you until you let go.
 
+Reactions
+~~~~~~~~~
 
+The reactions button lets you send an emoji reaction to all participants in the call.
 
+.. image:: images/calls/call-reactions.png
+    :width: 400px
 
+Every participant will see the emoji rising from the bottom of their call screen. The emoji disappears after two seconds.
 
+Raise hand
+^^^^^^^^^^
 
+Clicking ``Raise hand`` will notify moderators and show an icon next to your name. This is also available via the keyboard shortcut ``R``.
 
+Full screen
+^^^^^^^^^^^
 
-
-
-
-
+Resizes your browser window or the Talk Desktop client to full-screen mode.
+Also available via the keyboard shortcut ``F``. Press ``ESC`` to return to the regular view.

user_manual/talk/call_recording.rst

@@ -1,3 +1,5 @@
+.. _call-recording:
+
 Call recording
 ==============
 

user_manual/talk/call_screenshare.rst

@@ -2,10 +2,18 @@
 Screen sharing
 ==============
 
-You can click the monitor icon on your video stream to share your screen. Depending on your browser, you will get the option to share a monitor, an application window or a single browser tab.
+Click the monitor icon in the toolbar to share your screen.
+
+.. note:: If you have not yet given permission to the browser or the Talk Desktop client to share your screen,
+    you might be prompted to do so when you click ``Share screen``.
+    Please click on ``Allow`` to grant the browser or Talk Desktop client access to your screen.
+
+Depending on your browser or the Talk Desktop client, you will get the option to share a monitor, an application window, or a single browser tab.
 If video from your camera is also available, other participants will see it in a small presenter view next to the screen share.
 
 .. image:: images/share-screen-with-camera.png
     :width: 700px
 
+To stop sharing your screen, click the ``Share screen`` button again and choose ``Stop screensharing``.
+
 You can zoom in and out of the shared screen with the mouse wheel, double-click, or touchpad gestures.

user_manual/talk/call_views.rst

@@ -2,23 +2,24 @@
 Call layout
 ===========
 
-You can switch between promoted view and grid view using the toggle in the bottom bar.
+You can switch between grid view and speaker view using the toggle icon in the three-dot menu or the bottom bar.
 
 .. image:: images/call-view-toggle-button.png
     :width: 300px
 
 Grid view
 ---------
 
-Grid view shows as many participants as the screen can fit. Use the navigation buttons on the left and right to scroll through participants when there are more than the screen can display.
+Grid view shows all participants as tiles. Use the navigation buttons on the left and right to scroll through participants when they do not all fit on the screen.
 
 .. image:: images/talk-grid-view.png
     :width: 700px
 
-Promoted view
+Speaker view
 -------------
 
-Promoted view shows the active speaker large, with other participants in a row below. Use the navigation buttons on the left and right to scroll through participants when the row overflows.
+Speaker view (also called promoted view) centres the active speaker in a large tile and places the other participants in a row below.
+Use the navigation buttons on the left and right to scroll through participants when the row overflows.
 
 .. image:: images/talk-promoted-view.png
     :width: 700px