diff --git a/docs/README.md b/docs/README.md
index a473f1b23d..7285ad1146 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,3 +1,5 @@
+# Zed Docs
+
 Welcome to Zed's documentation.
 
 This is built on push to `main` and published automatically to [https://zed.dev/docs](https://zed.dev/docs).
@@ -8,7 +10,13 @@ To preview the docs locally you will need to install [mdBook](https://rust-lang.
 mdbook serve docs
 ```
 
-### Internal docs:
+## Images and videos
+
+To add images or videos to the docs, upload them to another location (e.g., zed.dev, GitHub's asset storage) and then link out to them from the docs.
+
+Putting binary assets such as images in the Git repository will bloat the repository size over time.
+
+## Internal notes:
 
 - We have a Cloudflare router called `docs-proxy`that intercepts requests to `zed.dev/docs` and forwards them to the "docs" Cloudflare Pages project.
 - CI uploads a new version to the Pages project from `.github/workflows/deploy_docs.yml` on every push to `main`.