Incorporate review

2 files changed, 13 insertions, 12 deletions

diff --git a/docs/delegate.md b/docs/delegate.md
index 57ae2c4c70..208ddb6277 100644
--- a/docs/delegate.md
+++ b/docs/delegate.md
@@ -1,13 +1,14 @@
 # Delegation
 
-Without configuring delegation, homeservers will expect the server
-responsible for resources using e.g. `example.com` as their `server_name`
-(e.g. `@user:example.com`) to be served at `example.com:8448`.
+By default, other homeservers will expect to be able to reach yours via
+your `server_name`, on port 8448. For example, if you set your `server_name`
+to `example.com` (so that your user names look like `@user:example.com`),
+other servers will try to connect to yours at `https://example.com:8448/`.
 
 Delegation is a Matrix feature allowing a homeserver admin to retain a
-`server_name` of `example.com` so that your user IDs, room aliases, etc
-continue to look like `*:example.com`, whilst having your federation
-traffic routed to a different server and/or port (e.g. `synapse.example.com:443`).
+`server_name` of `example.com` so that user IDs, room aliases, etc continue
+to look like `*:example.com`, whilst having federation traffic routed
+to a different server and/or port (e.g. `synapse.example.com:443`).
 
 ## .well-known delegation
 
@@ -37,8 +38,8 @@ should return:
 Note, specifying a port is optional. If no port is specified, then it defaults
 to 8448.
 
-With .well-known, federation servers will check for a valid TLS certificate
-for the delegated hostname (in our example: `synapse.example.com`).
+With .well-known delegation, federating servers will check for a valid TLS
+certificate for the delegated hostname (in our example: `synapse.example.com`).
 
 ## SRV DNS record delegation
 
diff --git a/docs/federate.md b/docs/federate.md
index 5fc839b58b..a0786b9cf7 100644
--- a/docs/federate.md
+++ b/docs/federate.md
@@ -12,10 +12,10 @@ it is also the domain that other servers will use to try to reach your
 server (via port 8448). This is easy to set up and will work provided
 you set the `server_name` to match your machine's public DNS hostname.
 
-You will also need a valid TLS certificate for this `server_name` served
-on port 8448. The preferred way to do that is by using a reverse proxy,
-see [reverse_proxy.md](<reverse_proxy.md>) for instructions on how to
-correctly set one up.
+For this default configuration to work, you will need to listen for TLS
+connections on port 8448. The preferred way to do that is by using a
+reverse proxy: see [reverse_proxy.md](<reverse_proxy.md>) for instructions
+on how to correctly set one up.
 
 In some cases you might not want to run Synapse on the machine that has
 the `server_name` as its public DNS hostname, or you might want federation