diff --git a/docs/components/alert/index.md b/docs/components/alert/index.md
index b3b8de9ced9c8db70bebe57d1a97bd8b2f0263c4..c9962fc9aa0b0bfea80a4cc5a2bf2d219f0e34e6 100644
--- a/docs/components/alert/index.md
+++ b/docs/components/alert/index.md
@@ -3,13 +3,13 @@
 
 | Prop          | Data type                                          | Required? | Default     | Description             |
 | ------------- | -------------------------------------------------- | --------- | ----------- | ----------------------- |
-| `color`       | `blue` \| `red` \| `purple` \| `green` \| `yellow` | No        | `secondary` | Renders a colored alert |
+| `color`       | `blue` \| `red` \| `purple` \| `green` \| `yellow` | No        | `secondary` | The color of the alert container |
 
 
 
 ## Alert colors
 
-Funkwhale alert support a range of pastel colors to create visually appealing interfaces.
+Funkwhale alerts support a range of pastel colors for visual appeal.
 
 ::: details Colors
 
diff --git a/docs/components/modal/index.md b/docs/components/modal/index.md
index 314125f0acf99d1487aed9ec964af54da56f4c46..6fe12ae47e5a915ffa8f58e2337f7cb074e09bdb 100644
--- a/docs/components/modal/index.md
+++ b/docs/components/modal/index.md
@@ -22,8 +22,8 @@ const open5 = ref(false)
 
 | Prop          | Data type         | Required? | Default | Description              |
 | ------------- | ----------------- | --------- | ------- | ------------------------ |
-| `title`       | `string`          | Yes       |         | Modal title              |
-| `v-model`     | `true` \| `false` | Yes       |         | Should the modal be open |
+| `title`       | `string`          | Yes       |         | The modal title              |
+| `v-model`     | `true` \| `false` | Yes       |         | Whether the modal is open or not |
 
 
 
@@ -49,6 +49,8 @@ const open5 = ref(false)
 
 ## Modal actions
 
+Use the `#actions` slot to add actions to a modal. Actions typically take the form of [buttons](/components/button/basic).
+
 ```vue-html
 <fw-modal v-model="open" title="My modal">
   Modal content
@@ -86,6 +88,8 @@ const open5 = ref(false)
 
 ## Nested modals
 
+You can nest modals to allow users to open a modal from inside another modal. This can be useful when creating a multi-step workflow.
+
 ```vue-html
 <fw-modal v-model="open" title="My modal">
   <fw-modal v-model="openNested" title="My modal">
@@ -116,6 +120,8 @@ const open5 = ref(false)
 
 ## Alert inside modal
 
+You can nest [Funkwhale alerts](/components/alert/) to visually highlight content within the modal.
+
 ```vue-html
 <fw-modal v-model="open" title="My modal">
   Modal content