diff --git a/INSTALL.md b/INSTALL.md
index a4a72b36b1..bda6741cb2 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -394,13 +394,13 @@ To configure Synapse to expose an HTTPS port, you will need to edit
   instance, if using certbot, use `fullchain.pem` as your certificate, not
   `cert.pem`).
 
-For those of you upgrading your TLS certificate in readiness for Synapse 1.0,
+For those of you upgrading your TLS certificate for Synapse 1.0 compliance,
 please take a look at [our guide](docs/MSC1711_certificates_FAQ.md#configuring-certificates-for-compatibility-with-synapse-100).
 
 ## Email
 
-It is desirable for Synapse to have the capability to send email.
-For example, this is required to support the 'password reset' feature.
+It is desirable for Synapse to have the capability to send email. For example,
+this is required to support the 'password reset' feature.
 
 To configure an SMTP server for Synapse, modify the configuration section
 headed ``email``, and be sure to have at least the ``smtp_host``, ``smtp_port``
@@ -410,13 +410,14 @@ and ``notif_from`` fields filled out. You may also need to set ``smtp_user``,
 If Synapse is not configured with an SMTP server, password reset via email will
  be disabled by default.
 
-Alternatively it is possible delegate the sending of email to the server's identity server.
-Doing so is convenient but not recommended, since a malicious or compromised identity server could
-theoretically hijack a given user's account by redirecting mail.
+Alternatively it is possible delegate the sending of email to the server's
+identity server. Doing so is convenient but not recommended, since a malicious
+or compromised identity server could theoretically hijack a given user's
+account by redirecting mail.
 
-If you are absolutely certain that you wish to use the server's identity
-server for password resets, set ``trust_identity_server_for_password_resets`` to ``true``
-under the ``email:`` configuration section.
+If you are absolutely certain that you wish to use the server's identity server
+for password resets, set ``trust_identity_server_for_password_resets`` to
+``true`` under the ``email:`` configuration section.
 
 ## Registering a user
 
diff --git a/UPGRADE.rst b/UPGRADE.rst
index 3cc1dbb344..06f667cae4 100644
--- a/UPGRADE.rst
+++ b/UPGRADE.rst
@@ -70,8 +70,7 @@ server in a closed federation. This can be done in one of two ways:-
  * Configure a whitelist of server domains to trust via
    ``federation_certificate_verification_whitelist``.
 
-See the `sample configuration file
-<https://github.com/matrix-org/synapse/blob/master/docs/sample_config.yaml>`_
+See the `sample configuration file <docs/sample_config.yaml>`_
 for more details on these settings. When a user requests
 a password reset, Synapse will send an email to the user to confirm the
 request.