diff --git a/README.md b/README.md
index 138733e3bc..88f9de2770 100644
--- a/README.md
+++ b/README.md
@@ -1725,7 +1725,7 @@ In embedded mode, you can access this port.  Example:
 import proxy
 
 if __name__ == '__main__':
-  with proxy.Proxy() as p:
+  with proxy.Proxy(port=0) as p:
     print(p.flags.port)
     proxy.sleep_loop()
 ```
diff --git a/docs/changelog-fragments.d/1524.doc.md b/docs/changelog-fragments.d/1524.doc.md
new file mode 100644
index 0000000000..9535b98949
--- /dev/null
+++ b/docs/changelog-fragments.d/1524.doc.md
@@ -0,0 +1 @@
+Clarify documentation for using ephemeral ports in embedded mode.