diff --git a/content/client-server-api/modules/mentions.md b/content/client-server-api/modules/mentions.md
index 21d91d8c..fab96ad6 100644
--- a/content/client-server-api/modules/mentions.md
+++ b/content/client-server-api/modules/mentions.md
@@ -13,26 +13,6 @@ the event to reference the entity being mentioned.
 
 {{% definition path="api/client-server/definitions/m.mentions" %}}
 
-Although it is possible to silently mention users, it is recommended to include a
-[Matrix URI](/appendices/#uris) in the HTML body of  an [m.room.message](#mroommessage)
-event. This applies only to [m.room.message](#mroommessage) events where the `msgtype` is
-`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
-`org.matrix.custom.html` and therefore requires a `formatted_body`.
-
-Similarly, the entire room can be mentioned:
-
-```json
-{
-    "body": "Hello @room!",
-    "msgtype": "m.text",
-    "format": "org.matrix.custom.html",
-    "formatted_body": "Hello @room!",
-    "m.mentions": {
-        "room": true
-    }
-}
-```
-
 Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and
 [`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules.
 Users should not add their own Matrix ID to the `m.mentions` property as outgoing
@@ -54,21 +34,26 @@ the event. This was prone to confusing and buggy behaviour.
 
 #### Client behaviour
 
-In addition to using the appropriate `Matrix URI` for the mention,
-clients should use the following guidelines when making mentions in
-events to be sent:
+Although it is possible to silently mention users, it is recommended to include a
+[Matrix URI](/appendices/#uris) in the HTML body of  an [m.room.message](#mroommessage)
+event. This applies only to [m.room.message](#mroommessage) events where the `msgtype` is
+`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
+`org.matrix.custom.html` and therefore requires a `formatted_body`.
 
--   When mentioning users, use the user's potentially ambiguous display
+Clients should use the following guidelines when adding a `Matrix URI`
+representing a mention to events to be sent:
+
+-   When linking to users, use the user's potentially ambiguous display
     name for the anchor's text. If the user does not have a display
     name, use the user's ID.
--   When mentioning rooms, use the canonical alias for the room. If the
+-   When linking to rooms, use the canonical alias for the room. If the
     room does not have a canonical alias, prefer one of the aliases
     listed on the room. If no alias can be found, fall back to the room
     ID. In all cases, use the alias/room ID being linked to as the
     anchor's text.
 
 The text component of the anchor should be used in the event's `body`
-where the mention would normally be represented, as shown in the example
+where the link would normally be represented, as shown in the example
 above.
 
 Clients should display mentions differently from other elements. For
@@ -77,7 +62,9 @@ mention to indicate that it is different from a normal link.
 
 If the current user is mentioned in a message, the client should show that
 mention differently from other mentions, such as by using a red
-background color to signify to the user that they were mentioned.
+background color to signify to the user that they were mentioned. Note that
+it is possible for a user to be mentioned without including their `Matrix URI`
+in the event.
 
 When clicked, the mention should navigate the user to the appropriate
 user or room information.