Split optional matrix howto steps into new docs

So that the "How to matrix" doc isn't so large, split the optional
add-on steps into separate documents.

Change-Id: I1ef1c8c0280dccda12fe0fd9c6498d202f769ab5

3 files changed, 118 insertions, 106 deletions

diff --git a/doc/source/howtos/matrix-encryption.rst b/doc/source/howtos/matrix-encryption.rst
new file mode 100644
index 000000000..10a895b0a
--- /dev/null
+++ b/doc/source/howtos/matrix-encryption.rst
@@ -0,0 +1,32 @@
+Optional: Save Encryption Keys
+==============================
+
+The Matrix protocol supports end-to-end encryption.  We don't have
+this enabled for the ``#zuul`` room (there's little point as it's a
+public room), but if you start direct chats with other Matrix users,
+your communication will be encrypted by default.  Since it's
+*end-to-end* encryption, that means your encryption keys are stored on
+your client, and the server has no way to decrypt those messages.  But
+that also means that if you sign out of your client or switch
+browsers, you will lose your encryption keys along with access to any
+old messages that were encrypted with them.  To avoid this, you can
+back up your keys to the server (in an encrypted form, of course) so
+that if you log in from another session, you can restore those keys
+and pick up where you left off.  To set this up, open the User Menu by
+clicking on your name at the top left of the screen.
+
+.. image:: /images/matrix/user-menu.png
+   :align: center
+
+Click the `Security & privacy` menu item in the dropdown.
+
+.. image:: /images/matrix/user-menu-dropdown.png
+   :align: center
+
+Click the `Set up` button under `Encryption` / `Secure Backup` in the
+dialog that pops up.
+
+.. image:: /images/matrix/user-encryption.png
+   :align: center
+
+Follow the prompts to back up your encryption keys.
diff --git a/doc/source/howtos/matrix-id.rst b/doc/source/howtos/matrix-id.rst
new file mode 100644
index 000000000..44203d83e
--- /dev/null
+++ b/doc/source/howtos/matrix-id.rst
@@ -0,0 +1,76 @@
+Optional: Register with an Identity Provider
+============================================
+
+By default, there is no public link between your Matrix account and
+any identifying information such as your email address.  However, you
+may wish people to be able to find your Matrix ID by looking up your
+email address or phone number.  We also have plans to add additional
+functionality to our bots if they are able to look up contributors by
+email addresses.  If you wish to make your account discoverable in
+this way, you may perform the following steps to list your account in
+one of the public third-party identifier services.  Note that these
+services are designed to only return results for someone who already
+knows your email address or phone number; they take care to ensure
+that it is not possible (or nearly so) to "scrape" their data sets to
+obtain lists of users.
+
+To get started, open the User Menu and click `All settings`.  Under
+the `General` section, find `Email addresses`.  If you followed the
+instructions above, you should already have an email address listed
+here.  If you don't, enter your address, click `Add`, and follow the
+instructions to verify your address.  The dialog should look like this
+when complete:
+
+.. image:: /images/matrix/id-email-complete.png
+   :align: center
+
+To make your account discoverable by email, scroll down to the
+`Discovery` section.
+
+.. image:: /images/matrix/id-disc.png
+   :align: center
+
+Read the privacy notice and click the checkbox
+next to `Accept`.  That will enable the `Continue` button; click that
+to proceed.
+
+.. image:: /images/matrix/id-disc-accept.png
+   :align: center
+
+The `Discovery` section will be replaced with the email address you
+registered above.
+
+.. image:: /images/matrix/id-disc-accept.png
+   :align: center
+
+Click the `Share` button next to the address.  The system will send an
+email to you, and meanwhile the dialog will show this:
+
+.. image:: /images/matrix/id-disc-verify-wait.png
+   :align: center
+
+You will receive an email like this:
+
+.. image:: /images/matrix/id-disc-verify-email.png
+   :align: center
+
+Follow the link in the email to verify it really is you making the
+request.
+
+.. image:: /images/matrix/id-disc-verify-success.png
+   :align: center
+
+Then return to the settings page and click the `Complete` button.
+
+.. image:: /images/matrix/id-disc-verify-wait.png
+   :align: center
+
+Once everything is finished, the complete button should change to read
+`Revoke`.
+
+.. image:: /images/matrix/id-disc-verify-complete.png
+   :align: center
+
+If you see that, you're all done.  If you change your mind and don't
+want your account to be discoverable via email, you can click the
+`Revoke` button at any time.
diff --git a/doc/source/howtos/matrix.rst b/doc/source/howtos/matrix.rst
index 16afae162..144466222 100644
--- a/doc/source/howtos/matrix.rst
+++ b/doc/source/howtos/matrix.rst
@@ -134,112 +134,16 @@ join.  Because Matrix keeps a message history, we'll see your message
 and you'll see any responses, even if you close your browser and log
 in later.
 
-Optional: Save Encryption Keys
-------------------------------
-
-The Matrix protocol supports end-to-end encryption.  We don't have
-this enabled for the ``#zuul`` room (there's little point as it's a
-public room), but if you start direct chats with other Matrix users,
-your communication will be encrypted by default.  Since it's
-*end-to-end* encryption, that means your encryption keys are stored on
-your client, and the server has no way to decrypt those messages.  But
-that also means that if you sign out of your client or switch
-browsers, you will lose your encryption keys along with access to any
-old messages that were encrypted with them.  To avoid this, you can
-back up your keys to the server (in an encrypted form, of course) so
-that if you log in from another session, you can restore those keys
-and pick up where you left off.  To set this up, open the User Menu by
-clicking on your name at the top left of the screen.
-
-.. image:: /images/matrix/user-menu.png
-   :align: center
-
-Click the `Security & privacy` menu item in the dropdown.
-
-.. image:: /images/matrix/user-menu-dropdown.png
-   :align: center
-
-Click the `Set up` button under `Encryption` / `Secure Backup` in the
-dialog that pops up.
-
-.. image:: /images/matrix/user-encryption.png
-   :align: center
-
-Follow the prompts to back up your encryption keys.
-
-Optional: Register with an Identity Provider
---------------------------------------------
-
-By default, there is no public link between your Matrix account and
-any identifying information such as your email address.  However, you
-may wish people to be able to find your Matrix ID by looking up your
-email address or phone number.  We also have plans to add additional
-functionality to our bots if they are able to look up contributors by
-email addresses.  If you wish to make your account discoverable in
-this way, you may perform the following steps to list your account in
-one of the public third-party identifier services.  Note that these
-services are designed to only return results for someone who already
-knows your email address or phone number; they take care to ensure
-that it is not possible (or nearly so) to "scrape" their data sets to
-obtain lists of users.
-
-To get started, open the User Menu and click `All settings`.  Under
-the `General` section, find `Email addresses`.  If you followed the
-instructions above, you should already have an email address listed
-here.  If you don't, enter your address, click `Add`, and follow the
-instructions to verify your address.  The dialog should look like this
-when complete:
-
-.. image:: /images/matrix/id-email-complete.png
-   :align: center
-
-To make your account discoverable by email, scroll down to the
-`Discovery` section.
-
-.. image:: /images/matrix/id-disc.png
-   :align: center
-
-Read the privacy notice and click the checkbox
-next to `Accept`.  That will enable the `Continue` button; click that
-to proceed.
-
-.. image:: /images/matrix/id-disc-accept.png
-   :align: center
-
-The `Discovery` section will be replaced with the email address you
-registered above.
+Optional Next Steps
+-------------------
 
-.. image:: /images/matrix/id-disc-accept.png
-   :align: center
-
-Click the `Share` button next to the address.  The system will send an
-email to you, and meanwhile the dialog will show this:
-
-.. image:: /images/matrix/id-disc-verify-wait.png
-   :align: center
-
-You will receive an email like this:
-
-.. image:: /images/matrix/id-disc-verify-email.png
-   :align: center
+The following steps are optional.  You don't need to do these just to
+hop in with a quick question, but if you plan on spending more than a
+brief amount of time interacting with communities in Matrix, they will
+improve your experience.
 
-Follow the link in the email to verify it really is you making the
-request.
-
-.. image:: /images/matrix/id-disc-verify-success.png
-   :align: center
-
-Then return to the settings page and click the `Complete` button.
-
-.. image:: /images/matrix/id-disc-verify-wait.png
-   :align: center
-
-Once everything is finished, the complete button should change to read
-`Revoke`.
-
-.. image:: /images/matrix/id-disc-verify-complete.png
-   :align: center
+.. toctree::
+   :maxdepth: 1
 
-If you see that, you're all done.  If you change your mind and don't
-want your account to be discoverable via email, you can click the
-`Revoke` button at any time.
+   matrix-encryption
+   matrix-id