Update worker docs to update preferred settings for pusher and federation_sender (#14493)

* Fix one typo on line 3700(and apparently do something to other lines, no idea)

* Update config_documentation.md with more information about how federation_senders and pushers settings can be handled.

Specifically, that the instance map style of config does not require the special other variables that enable and disable functionality and that a single worker CAN be added to the map not only just two or more.

* Extra line here for consistency and appearance.

* Add link to sygnal repo.

* Add deprecation notice to workers.md and point to the newer alternative method of defining this functionality.

* Changelog

* Correct version number of Synapse the deprecation is happening in.

* Update quiet deprecation with simple notice and suggestion.

changelog.d/14493.doc

@@ -0,0 +1 @@
+Update worker settings for `pusher` and `federation_sender` functionality.

docs/usage/configuration/config_documentation.md

@@ -3684,7 +3684,7 @@ As a result, the worker configuration is divided into two parts.
 
 1. The first part (in this section of the manual) defines which shardable tasks
    are delegated to privileged workers. This allows unprivileged workers to make
-   request a privileged worker to act on their behalf.
+   requests to a privileged worker to act on their behalf.
 1. [The second part](#individual-worker-configuration)
    controls the behaviour of individual workers in isolation.
 
@@ -3706,6 +3706,8 @@ worker_replication_secret: "secret_secret"
 ---
 ### `start_pushers`
 
+Unnecessary to set if using [`pusher_instances`](#pusher_instances) with [`generic_workers`](../../workers.md#synapseappgeneric_worker).
+
 Controls sending of push notifications on the main process. Set to `false`
 if using a [pusher worker](../../workers.md#synapseapppusher). Defaults to `true`.
 
@@ -3716,25 +3718,30 @@ start_pushers: false
 ---
 ### `pusher_instances`
 
-It is possible to run multiple [pusher workers](../../workers.md#synapseapppusher),
+It is possible to scale the processes that handle sending push notifications to [sygnal](https://github.com/matrix-org/sygnal)
-in which case the work is balanced across them. Use this setting to list the pushers by
+and email by running a [`generic_worker`](../../workers.md#synapseappgeneric_worker) and adding it's [`worker_name`](#worker_name) to
-[`worker_name`](#worker_name). Ensure the main process and all pusher workers are
+a `pusher_instances` map. Doing so will remove handling of this function from the main
-restarted after changing this option.
+process. Multiple workers can be added to this map, in which case the work is balanced
+across them. Ensure the main process and all pusher workers are restarted after changing
+this option.
 
-If no or only one pusher worker is configured, this setting is not necessary.
+Example configuration for a single worker:
-The main process will send out push notifications by default if you do not disable
+```yaml
-it by setting [`start_pushers: false`](#start_pushers).
+pusher_instances:
-
+  - pusher_worker1
-Example configuration:
+```
+And for multiple workers:
 ```yaml
-start_pushers: false
 pusher_instances:
   - pusher_worker1
   - pusher_worker2
 ```
+
 ---
 ### `send_federation`
 
+Unnecessary to set if using [`federation_sender_instances`](#federation_sender_instances) with [`generic_workers`](../../workers.md#synapseappgeneric_worker).
+
 Controls sending of outbound federation transactions on the main process.
 Set to `false` if using a [federation sender worker](../../workers.md#synapseappfederation_sender).
 Defaults to `true`.
@@ -3746,21 +3753,28 @@ send_federation: false
 ---
 ### `federation_sender_instances`
 
-It is possible to run multiple
+It is possible to scale the processes that handle sending outbound federation requests
-[federation sender worker](../../workers.md#synapseappfederation_sender), in which
+by running a [`generic_worker`](../../workers.md#synapseappgeneric_worker) and adding it's [`worker_name`](#worker_name) to
-case the work is balanced across them. Use this setting to list the senders.
+a `federation_sender_instances` map. Doing so will remove handling of this function from
+the main process. Multiple workers can be added to this map, in which case the work is
+balanced across them.
 
-This configuration setting must be shared between all federation sender workers, and if
+This configuration setting must be shared between all workers handling federation
-changed all federation sender workers must be stopped at the same time and then
+sending, and if changed all federation sender workers must be stopped at the same time
-started, to ensure that all instances are running with the same config (otherwise
+and then started, to ensure that all instances are running with the same config (otherwise
 events may be dropped).
 
-Example configuration:
+Example configuration for a single worker:
 ```yaml
-send_federation: false
 federation_sender_instances:
   - federation_sender1
 ```
+And for multiple workers:
+```yaml
+federation_sender_instances:
+  - federation_sender1
+  - federation_sender2
+```
 ---
 ### `instance_map`
 
@@ -3988,4 +4002,3 @@ background_updates:
     min_batch_size: 10
     default_batch_size: 50
 ```
-

docs/workers.md

@@ -505,6 +505,9 @@ worker application type.
 
 ### `synapse.app.pusher`
 
+It is likely this option will be deprecated in the future and is not recommended for new
+installations. Instead, [use `synapse.app.generic_worker` with the `pusher_instances`](usage/configuration/config_documentation.md#pusher_instances).
+
 Handles sending push notifications to sygnal and email. Doesn't handle any
 REST endpoints itself, but you should set
 [`start_pushers: false`](usage/configuration/config_documentation.md#start_pushers) in the
@@ -543,6 +546,9 @@ Note this worker cannot be load-balanced: only one instance should be active.
 
 ### `synapse.app.federation_sender`
 
+It is likely this option will be deprecated in the future and not recommended for
+new installations. Instead, [use `synapse.app.generic_worker` with the `federation_sender_instances`](usage/configuration/config_documentation.md#federation_sender_instances). 
+
 Handles sending federation traffic to other servers. Doesn't handle any
 REST endpoints itself, but you should set
 [`send_federation: false`](usage/configuration/config_documentation.md#send_federation)
@@ -639,7 +645,9 @@ equivalent to `synapse.app.generic_worker`:
  * `synapse.app.client_reader`
  * `synapse.app.event_creator`
  * `synapse.app.federation_reader`
+ * `synapse.app.federation_sender`
  * `synapse.app.frontend_proxy`
+ * `synapse.app.pusher`
  * `synapse.app.synchrotron`