From d74ddcac95dc20a841e2860b95f82507159f8cc5 Mon Sep 17 00:00:00 2001
From: Eeshan Garg <jerryguitarist@gmail.com>
Date: Mon, 11 Jun 2018 22:32:57 -0230
Subject: [PATCH] integrations/matrix: Update docs to conform to style guide.

This is a follow-up to #9491.
---
 .../zerver/help/include/install-matrix.md     | 11 ++---
 templates/zerver/integrations/matrix.md       | 42 ++++++++++---------
 2 files changed, 27 insertions(+), 26 deletions(-)

diff --git a/templates/zerver/help/include/install-matrix.md b/templates/zerver/help/include/install-matrix.md
index 291aadacc4..f240e57fca 100644
--- a/templates/zerver/help/include/install-matrix.md
+++ b/templates/zerver/help/include/install-matrix.md
@@ -1,8 +1,6 @@
 ### Install the bridge software
 
-You can install the bridge software as follows:
-
-1.  First, clone the Zulip API and install its dependencies:
+1. Clone the Zulip API repository, and install its dependencies:
 
     ```
     git clone https://github.com/zulip/python-zulip-api.git
@@ -10,10 +8,10 @@ You can install the bridge software as follows:
     python3 ./tools/provision
     ```
 
-1. Next, enter the virtualenv, by running the `source` command printed
+1. Activate the virtualenv by running the `source` command printed
    at the end of the `provision` output.
 
-1.  Then, run this to install the Matrix bridge software in your virtualenv.
+1. To install the Matrix bridge software in your virtualenv, run:
 
     ```
     pip install -r zulip/integrations/matrix/requirements.txt
@@ -21,5 +19,4 @@ You can install the bridge software as follows:
 
 This will create a new Python virtual environment, with all the
 dependences for this bridge installed.  You'll want to run the bridge
-service inside this virtualenv.  If you later need to enter the
-virtualenv (from e.g. a new shell), you can use the `source` command.
+service inside this virtualenv.
diff --git a/templates/zerver/integrations/matrix.md b/templates/zerver/integrations/matrix.md
index 7f0572f76a..c5795eb519 100644
--- a/templates/zerver/integrations/matrix.md
+++ b/templates/zerver/integrations/matrix.md
@@ -4,17 +4,15 @@ A bridge for exchanging messages between [matrix.org](https://matrix.org) and Zu
 
 ### Configure the bridge
 
-{!create-stream.md!}
+1. {!create-stream.md!}
 
-1. Next, on your Zulip settings page, create a generic bot for Matrix,
-   preferably with a formal name like `matrix-bot`.
+1. On your {{ settings_html|safe }}, create a **Generic** bot for
+   {{ integration_display_name }}. Subscribe this bot to the stream
+   created in step 1.
 
-1. Subscribe this bot to the Zulip stream where you'd like the bridge
-   traffic to be sent.
-
-1.  Edit `zulip/integrations/matrix/matrix_bridge_config.py`, providing
-    the following values for the `zulip` section (the first 3 values
-    come from a `zuliprc` file):
+1. Open `zulip/integrations/matrix/matrix_bridge_config.py` with your
+   favorite editor, and change the following lines in the `zulip`
+   section:
 
     ```
     "zulip": {
@@ -26,10 +24,16 @@ A bridge for exchanging messages between [matrix.org](https://matrix.org) and Zu
     }
     ```
 
-1. Now, create a user on [matrix.org](https://matrix.org/), preferably
-   with a formal name like `zulip-bot`.
+    **email**, **api_key**, and **site** should come from your
+    {{ integration_display_name }} bot's `zuliprc` file. Set **stream**
+    to the name of the stream created in step 1, and set **topic** to
+    a topic of your choice.
 
-1.  Edit `matrix_bridge_config.py` to add the Matrix-side settings:
+1. Create a user on [matrix.org](https://matrix.org/), preferably
+   with a descriptive name such as `zulip-bot`.
+
+1. Open `matrix_bridge_config.py`, and provide your Matrix credentials
+   in the `matrix` section:
 
     ```
     "matrix": {
@@ -40,13 +44,13 @@ A bridge for exchanging messages between [matrix.org](https://matrix.org) and Zu
     }
     ```
 
-1. After the steps above have been completed, run `python matrix_bridge.py` to
-start mirroring content.
+1. Run `python matrix_bridge.py` to start mirroring content.
 
-If you want to customize the message formatting, you can do so by
-editing the variables `MATRIX_MESSAGE_TEMPLATE` and
-`ZULIP_MESSAGE_TEMPLATE` in
-`zulip/integrations/matrix/matrix_bridge.py`, with a suitable
-template.
+!!! tip ""
+
+    If you want to customize the message formatting, you can do so by
+    editing the variables `MATRIX_MESSAGE_TEMPLATE` and
+    `ZULIP_MESSAGE_TEMPLATE` in
+    `zulip/integrations/matrix/matrix_bridge.py`.
 
 **Congratulations! You have created the bridge successfully!**