diff --git a/changelog.d/18548.doc b/changelog.d/18548.doc
new file mode 100644
index 00000000000..69b073221bf
--- /dev/null
+++ b/changelog.d/18548.doc
@@ -0,0 +1 @@
+Document that some config options for the user directory are in violation of the Matrix spec.
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 1e8953ae376..9cd88a97672 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -770,7 +770,7 @@ This setting has the following sub-options:
 
 * `default_user_type` (string|null): The default user type to use for registering new users when no value has been specified. Defaults to none. Defaults to `null`.
 
-* `extra_user_types` (list): Array of additional user types to allow. These are treated as real users. Defaults to `[]`.
+* `extra_user_types` (array): Array of additional user types to allow. These are treated as real users. Defaults to `[]`.
 
 Example configuration:
 ```yaml
@@ -3732,9 +3732,11 @@ encryption_enabled_by_default_for_room_type: invite
 
 *(object)* This setting defines options related to the user directory.
 
+*Warning: The Matrix spec requires homeservers to consider at least users the requesting user shares a room with and users who reside in public rooms known to the homeserver in directory searches. Some of the settings below aid performance but are in violation of this requirement.*
+
 This setting has the following sub-options:
 
-* `enabled` (boolean): Defines whether users can search the user directory. If false then empty responses are returned to all queries. Defaults to `true`.
+* `enabled` (boolean): Defines whether users can search the user directory. If `false`, then empty responses are returned to all queries (which is not spec-compliant). Defaults to `true`.
 
 * `search_all_users` (boolean): Defines whether to search all users visible to your homeserver at the time the search is performed. If set to true, will return all users known to the homeserver matching the search query. If false, search results will only contain users visible in public rooms and users sharing a room with the requester.
 
@@ -3746,7 +3748,7 @@ This setting has the following sub-options:
 
 * `prefer_local_users` (boolean): Defines whether to prefer local users in search query results. If set to true, local users are more likely to appear above remote users when searching the user directory. Defaults to `false`.
 
-* `exclude_remote_users` (boolean): If set to true, the search will only return local users. Defaults to `false`.
+* `exclude_remote_users` (boolean): If set to `true`, the search will only return local users (which is not spec-compliant). Defaults to `false`.
 
 * `show_locked_users` (boolean): Defines whether to show locked users in search query results. Defaults to `false`.
 
diff --git a/schema/synapse-config.schema.yaml b/schema/synapse-config.schema.yaml
index 52a6d5cf71b..030f48c9950 100644
--- a/schema/synapse-config.schema.yaml
+++ b/schema/synapse-config.schema.yaml
@@ -4643,13 +4643,20 @@ properties:
       - invite
   user_directory:
     type: object
-    description: This setting defines options related to the user directory.
+    description: >-
+      This setting defines options related to the user directory.
+
+
+      *Warning: The Matrix spec requires homeservers to consider at least users
+      the requesting user shares a room with and users who reside in public
+      rooms known to the homeserver in directory searches. Some of the settings
+      below aid performance but are in violation of this requirement.*
     properties:
       enabled:
         type: boolean
         description: >-
-          Defines whether users can search the user directory. If false then
-          empty responses are returned to all queries.
+          Defines whether users can search the user directory. If `false`, then
+          empty responses are returned to all queries (which is not spec-compliant).
         default: true
       search_all_users:
         type: boolean
@@ -4682,7 +4689,9 @@ properties:
         default: false
       exclude_remote_users:
         type: boolean
-        description: If set to true, the search will only return local users.
+        description: >-
+          If set to `true`, the search will only return local users (which is not
+          spec-compliant).
         default: false
       show_locked_users:
         type: boolean