diff --git a/api/client-server/v1/membership.yaml b/api/client-server/v1/membership.yaml
index 1845ce09..b86e8b03 100644
--- a/api/client-server/v1/membership.yaml
+++ b/api/client-server/v1/membership.yaml
@@ -18,7 +18,7 @@ securityDefinitions:
     name: access_token
     in: query
 paths:
-  "/room/{roomId}/join":
+  "/rooms/{roomId}/join":
     post:
       summary: Start the requesting user participating in a particular room.
       description: |-
@@ -26,6 +26,9 @@ paths:
         is allowed to participate in that room. After this call, the client is
         allowed to see all current state events in the room, and all subsequent
         events associated with the room until the user leaves the room.
+
+        After a user has joined a room, the room will appear as an entry in the
+        response of the |initialSync| API.
       security:
         - accessToken: []
       parameters:
@@ -40,19 +43,15 @@ paths:
           description: |-
             The room has been joined.
 
-            If the room was joined with an room alias, rather than a room ID,
-            the room ID must be returned in the room_id field.
-
-            If the room was joined with a room ID, the room_id field must not be
-            present.
+            The joined room ID must be returned in the room_id field.
           examples:
             application/json: |-
-              {"room_id": "!primates:matrix.org"}
+              {"room_id": "!d41d8cd:matrix.org"}
           schema:
             type: object  # empty json object
         403:
           description: |-
-            You do not have permission to join the room. A meaningful errcode and description error text will be returned. Example reasons for rejection are:
+            You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
               - The room is invite-only and the user was not invited.
               - The user has been banned from the room.
           examples:
@@ -62,6 +61,7 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-      x-aliases:
-        - /join/{roomId}
-      x-alias-link: "post-matrix-client-api-v1-room-roomid-join"
+      x-alias:
+        canonical-link: "post-matrix-client-api-v1-rooms-roomid-join"
+        aliases:
+          - /join/{roomId}
diff --git a/specification/10_client_server_api.rst b/specification/10_client_server_api.rst
index d0942ad6..1fdb9ae6 100644
--- a/specification/10_client_server_api.rst
+++ b/specification/10_client_server_api.rst
@@ -879,6 +879,16 @@ The keys contained in ``m.room.power_levels`` determine the levels required for
 certain operations such as kicking, banning and sending state events. See
 `m.room.power_levels`_ for more information.
 
+Joining rooms
+-------------
+Users need to be a member of a room in order to send and receive events in that
+room. There are several states in which a user may be, in relation to a room:
+
+ - Unrelated (the user cannot send or receive events in the room)
+ - Invited (the user has been invited to participate in the room, but is not
+   yet participating)
+ - Joined (the user can send and receive events in the room)
+ - Banned (the user is not allowed to join the room)
 
 {{membership_http_api}}