accepting suggested edits after rename mess

docs/configuring-playbook-bridges.md

@@ -1,11 +1,14 @@
-# Setting up a Generic Mautrix Bridge (optional)
+# Setting up a Mautrix Bridge (optional)
+
 
-The playbook can install and configure bridges with mautrix (Currently twitter, facebook, instagram, signal, hangouts, googlechat)
+# Setting up a Generic Mautrix Bridge (optional)
 
+The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, facebook, instagram, signal, hangouts, googlechat, etc.), as well as many other (non-mautrix) bridges.
+This is a common guide for configuring mautrix bridges.
 
-You can see each bridge features at https://github.com/mautrix/SERVICENAME/blob/master/ROADMAP.md
+You can see each bridge's features at in the `ROADMAP.md` file in its corresponding [mautrix](https://github.com/mautrix) repository.
 
-To enable a bridge add
+To enable a bridge add:
 
 
 ```yaml
@@ -14,14 +17,15 @@ matrix_mautrix_SERVICENAME_enabled: true
 
 to your `vars.yml`
 
-There are some additional things you may wish to configure about the bridge before you continue.
+There are some additional things you may wish to configure about the bridge before you continue. Each bridge may have additional requirements besides `_enabled: true`. For example, the mautrix-telegram bridge (our documentation page about it is [here](configuring-playbook-bridge-mautrix-telegram.md)) requires the `matrix_mautrix_telegram_api_id` and `matrix_mautrix_telegram_api_hash` variables to be defined. Refer to each bridge's individual documentation page for details about enabling bridges.
 
 You can add
 
 ```yaml
 matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
 ```
-to 'vars.yml' to configure a user as administrator for all bridges, or you prefer to do it bridge by bridge you can configure it with
+to `vars.yml` to **configure a user as an administrator for all bridges**.
+**Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with:
 
 ```yaml
 matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
@@ -40,7 +44,7 @@ matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
 ```
 
 
-Using both would look like
+You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this:
 
 ```yaml
 matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
@@ -52,12 +56,15 @@ matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
       default: true
 ```
 
+## Setting the bot's username
+
 ```yaml
 matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
 ```
 
 Can be used to set the username for the bridge.
 
+## Discovering additional configuration options
 
 You may wish to look at `roles/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` and `roles/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` to find other things you would like to configure.
 
@@ -93,4 +100,5 @@ If you run into trouble, check the [Troubleshooting](#troubleshooting) section b
 
 ## Troubleshooting
 
-Please see SERVICENAME's individual doc page for troubleshooting information.
+For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge.
+Reporting bridge bugs should happen upstream, in the corresponding mautrix repository, not to us.