diff --git a/docs/log_contexts.md b/docs/log_contexts.md
index d49dce8830..cb15dbe158 100644
--- a/docs/log_contexts.md
+++ b/docs/log_contexts.md
@@ -10,7 +10,7 @@ Logcontexts are also used for CPU and database accounting, so that we
can track which requests were responsible for high CPU use or database
activity.
-The `synapse.logging.context` module provides a facilities for managing
+The `synapse.logging.context` module provides facilities for managing
the current log context (as well as providing the `LoggingContextFilter`
class).
@@ -351,7 +351,7 @@ and the awaitable chain is now orphaned, and will be garbage-collected at
some point. Note that `await_something_interesting` is a coroutine,
which Python implements as a generator function. When Python
garbage-collects generator functions, it gives them a chance to
-clean up by making the `async` (or `yield`) raise a `GeneratorExit`
+clean up by making the `await` (or `yield`) raise a `GeneratorExit`
exception. In our case, that means that the `__exit__` handler of
`PreserveLoggingContext` will carefully restore the request context, but
there is now nothing waiting for its return, so the request context is
diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index e15a832220..95cca16552 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -2086,7 +2086,7 @@ password_config:
#
#require_lowercase: true
- # Whether a password must contain at least one lowercase letter.
+ # Whether a password must contain at least one uppercase letter.
# Defaults to 'false'.
#
#require_uppercase: true
diff --git a/docs/user_directory.md b/docs/user_directory.md
index d4f38d2cf1..07fe954891 100644
--- a/docs/user_directory.md
+++ b/docs/user_directory.md
@@ -10,3 +10,40 @@ DB corruption) get stale or out of sync. If this happens, for now the
solution to fix it is to execute the SQL [here](https://github.com/matrix-org/synapse/blob/master/synapse/storage/schema/main/delta/53/user_dir_populate.sql)
and then restart synapse. This should then start a background task to
flush the current tables and regenerate the directory.
+
+Data model
+----------
+
+There are five relevant tables that collectively form the "user directory".
+Three of them track a master list of all the users we could search for.
+The last two (collectively called the "search tables") track who can
+see who.
+
+From all of these tables we exclude three types of local user:
+ - support users
+ - appservice users
+ - deactivated users
+
+* `user_directory`. This contains the user_id, display name and avatar we'll
+ return when you search the directory.
+ - Because there's only one directory entry per user, it's important that we only
+ ever put publicly visible names here. Otherwise we might leak a private
+ nickname or avatar used in a private room.
+ - Indexed on rooms. Indexed on users.
+
+* `user_directory_search`. To be joined to `user_directory`. It contains an extra
+ column that enables full text search based on user ids and display names.
+ Different schemas for SQLite and Postgres with different code paths to match.
+ - Indexed on the full text search data. Indexed on users.
+
+* `user_directory_stream_pos`. When the initial background update to populate
+ the directory is complete, we record a stream position here. This indicates
+ that synapse should now listen for room changes and incrementally update
+ the directory where necessary.
+
+* `users_in_public_rooms`. Contains associations between users and the public rooms they're in.
+ Used to determine which users are in public rooms and should be publicly visible in the directory.
+
+* `users_who_share_private_rooms`. Rows are triples `(L, M, room id)` where `L`
+ is a local user and `M` is a local or remote user. `L` and `M` should be
+ different, but this isn't enforced by a constraint.
|
