Merge branch 'eread/refactor-polling-interval-multiplier-admin-area-config' into 'master'

Refactor polling interval multiplier configuration UI and docs

See merge request gitlab-org/gitlab!66342

app/views/admin/application_settings/_realtime.html.haml

@@ -6,7 +6,6 @@
       = f.label :polling_interval_multiplier, _('Polling interval multiplier'), class: 'label-bold'
       = f.text_field :polling_interval_multiplier, class: 'form-control gl-form-input'
       .form-text.text-muted
-        = _("Change this value to influence how frequently the GitLab UI polls for updates. If you set the value to 2 all polling intervals are multiplied by 2, which means that polling happens half as frequently. The multiplier can also have a decimal value. The default value (1) is a reasonable choice for the majority of GitLab installations. Set to 0 to completely disable polling.")
-        = link_to sprite_icon('question-o'), help_page_path('administration/polling')
+        = _('Multiplier to apply to polling intervals. Decimal values are supported. Defaults to 1.')
 
   = f.submit _('Save changes'), class: "gl-button btn btn-confirm"

app/views/admin/application_settings/preferences.html.haml

@@ -50,11 +50,12 @@
 %section.settings.as-realtime.no-animate#js-realtime-settings{ class: ('expanded' if expanded_by_default?) }
   .settings-header
     %h4
-      = _('Real-time features')
+      = _('Polling interval multiplier')
     %button.btn.gl-button.btn-default.js-settings-toggle{ type: 'button' }
       = expanded_by_default? ? _('Collapse') : _('Expand')
     %p
-      = _('Change this value to influence how frequently the GitLab UI polls for updates.')
+      = _('Adjust how frequently the GitLab UI polls for updates.')
+      = link_to _('Learn more.'), help_page_path('administration/polling.md'), target: '_blank', rel: 'noopener noreferrer'
   .settings-content
     = render 'realtime'
 

doc/administration/polling.md

@@ -4,29 +4,31 @@ group: Distribution
 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
 ---
 
-# Polling configuration **(FREE SELF)**
+# Polling interval multiplier **(FREE SELF)**
 
-The GitLab UI polls for updates for different resources (issue notes, issue
-titles, pipeline statuses, and so on) on a schedule appropriate to the resource.
+The GitLab UI polls for updates for different resources (issue notes, issue titles, pipeline
+statuses, and so on) on a schedule appropriate to the resource.
 
-To configure the polling interval multiplier:
+Adjust the multiplier on these schedules to adjust how frequently the GitLab UI polls for updates. If
+you set the multiplier to:
+
+- A value greater than `1`, UI polling slows down. If you see issues with database load from lots of
+  clients polling for updates, increasing the multiplier can be a good alternative to disabling
+  polling completely. For example, if you set the value to `2`, all polling intervals
+  are multiplied by 2, which means that polling happens half as frequently.
+- A value between `0` and `1`, the UI polls more frequently so updates occur more frequently.
+  **Not recommended**.
+- `0`, all polling is disabled. On the next poll, clients stop polling for updates.
+
+The default value (`1`) is recommended for the majority of GitLab installations.
+
+## Configure
+
+To adjust the polling interval multiplier:
 
 1. On the top bar, select **Menu >** **{admin}** **Admin**.
 1. On the left sidebar, select **Settings > Preferences**.
-1. Expand **Real-time features**.
-1. Set a value for the polling interval multiplier. This multiplier is applied
-   to all resources at once, and decimal values are supported:
-
-   - `1.0` is the default, and recommended for most installations.
-   - `0` disables UI polling completely. On the next poll, clients stop
-     polling for updates.
-   - A value greater than `1` slows polling down. If you see issues with
-     database load from lots of clients polling for updates, increasing the
-     multiplier from 1 can be a good compromise, rather than disabling polling
-     completely. For example, if you set the value to `2`, all polling intervals
-     are multiplied by 2, which means that polling happens half as frequently.
-   - A value between `0` and `1` makes the UI poll more frequently (so updates
-     show in other sessions faster), but is **not recommended**. `1` should be
-     fast enough.
-
+1. Expand **Polling interval multiplier**.
+1. Set a value for the polling interval multiplier. This multiplier is applied to all resources at
+   once.
 1. Select **Save changes**.

doc/user/admin_area/settings/index.md

@@ -115,7 +115,7 @@ To access the default page for Admin Area settings:
 | [What's new](../../../administration/whats-new.md) | Configure What's new drawer and content. |
 | [Help page](help_page.md) | Help page text and support page URL. |
 | [Pages](../../../administration/pages/index.md#custom-domain-verification) | Size and domain settings for static websites |
-| [Real-time features](../../../administration/polling.md) | Change this value to influence how frequently the GitLab UI polls for updates. |
+| [Polling interval multiplier](../../../administration/polling.md) | Configure how frequently the GitLab UI polls for updates. |
 | [Gitaly timeouts](gitaly_timeouts.md) | Configure Gitaly timeouts. |
 | Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). |
 

locale/gitlab.pot

@@ -2212,6 +2212,9 @@ msgstr ""
 msgid "Adds email participant(s)"
 msgstr ""
 
+msgid "Adjust how frequently the GitLab UI polls for updates."
+msgstr ""
+
 msgid "Adjust your filters/search criteria above. If you believe this may be an error, please refer to the %{linkStart}Geo Troubleshooting%{linkEnd} documentation for more information."
 msgstr ""
 
@@ -6172,12 +6175,6 @@ msgstr ""
 msgid "Change template"
 msgstr ""
 
-msgid "Change this value to influence how frequently the GitLab UI polls for updates."
-msgstr ""
-
-msgid "Change this value to influence how frequently the GitLab UI polls for updates. If you set the value to 2 all polling intervals are multiplied by 2, which means that polling happens half as frequently. The multiplier can also have a decimal value. The default value (1) is a reasonable choice for the majority of GitLab installations. Set to 0 to completely disable polling."
-msgstr ""
-
 msgid "Change title"
 msgstr ""
 
@@ -21477,6 +21474,9 @@ msgstr ""
 msgid "Multiple uploaders found: %{uploader_types}"
 msgstr ""
 
+msgid "Multiplier to apply to polling intervals. Decimal values are supported. Defaults to 1."
+msgstr ""
+
 msgid "Must match with the %{codeStart}external_url%{codeEnd} in %{codeStart}/etc/gitlab/gitlab.rb%{codeEnd}."
 msgstr ""
 
@@ -26882,9 +26882,6 @@ msgstr ""
 msgid "Ready to get started with GitLab? Follow these steps to set up your workspace, plan and commit changes, and deploy your project."
 msgstr ""
 
-msgid "Real-time features"
-msgstr ""
-
 msgid "Reauthenticating with SAML provider."
 msgstr ""