diff --git a/docs/README.md b/docs/README.md
index 9ae3f3c2..9685e5df 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,7 +5,13 @@ This documentation is intended to give an overview of how the `matrix-authentica
 The documentation itself is built using [mdBook](https://rust-lang.github.io/mdBook/).
 A hosted version is available at <https://matrix-org.github.io/matrix-authentication-service/>.
 
-## Links
+## How the documentation is organized
 
- - Technical documentation for individual crates: [`rustdoc`](./rustdoc/mas_handlers/)
- - UI components: [`storybook`](./storybook/)
+This documentation has four main sections:
+
+- The [installation guide](./setup/README.md) will guide you through the process of setting up the `matrix-authentication-service` on your own infrastructure.
+- The topics sections goes into more details about how the service works, like the [policy engine](./topics/policy.md) and how [authorization sessions](./topics/authorization.md) are managed.
+- The reference documentation covers [configuration options](./reference/configuration.md), the [GraphQL API](./reference/graphql.md), the [scopes](./reference/scopes.md) supported by the service, and the [command line interface](./reference/cli/).
+- The developer documentation is intended for people who want to [contribute to the project](./development/contributing.md). Other links:
+  - Technical documentation for individual crates: [`rustdoc`](./rustdoc/mas_handlers/)
+  - UI components: [`storybook`](./storybook/)
diff --git a/docs/reference/scopes.md b/docs/reference/scopes.md
index 031ac7fe..bf126a1a 100644
--- a/docs/reference/scopes.md
+++ b/docs/reference/scopes.md
@@ -96,12 +96,14 @@ This allows the authenticated entity to perform any operation on the API, regard
 The default policy doesn't allow everyone to request this scope.
 It allows:
 
-- for the "authorization code" and "device authorization" grants:
+- for the "[authorization code]" and "[device authorization]" grants:
   - users with the `can_request_admin` attribute set to `true` in the database
   - users listed in the [`policy.data.admin_users`](../reference/configuration.md#policy) configuration option
 - for the "client credentials" grant:
   - clients that are listed in the [`policy.data.admin_clients`](../reference/configuration.md#policy) configuration option
 
+[authorization code]: ../topics/authorization.md#authorization-code-grant
+[device authorization]: ../topics/authorization.md#device-authorization-grant
 [GraphQL API]: ./graphql.md
 [Synapse admin API]: https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html
 [OpenID Connect Core 1.0]: https://openid.net/specs/openid-connect-core-1_0.html