diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md
index 43c6ff6345..8b842c0399 100644
--- a/compose/compose-file/compose-file-v2.md
+++ b/compose/compose-file/compose-file-v2.md
@@ -1444,6 +1444,10 @@ The Docker Engine returns an error if the driver is not available.
 
     driver: overlay
 
+Starting in Compose file format 2.1, overlay networks are always created as
+`attachable`, and this is not configurable. This means that standalone
+containers can connect to overlay networks.
+
 ### driver_opts
 
 Specify a list of options as key-value pairs to pass to the driver for this
diff --git a/compose/networking.md b/compose/networking.md
index eaf96e32f0..e02fb4912c 100644
--- a/compose/networking.md
+++ b/compose/networking.md
@@ -39,6 +39,15 @@ When you run `docker-compose up`, the following happens:
 3.  A container is created using `db`'s configuration. It joins the network
     `myapp_default` under the name `db`.
 
+> **In v2.1+, overlay networks are always `attachable`**
+>
+> Starting in Compose file format 2.1, overlay networks are always created as
+> `attachable`, and this is not configurable. This means that standalone
+> containers can connect to overlay networks.
+>
+> In Compose file format 3.x, you can optionally set the `attachable` property
+> to `false`.
+
 Each container can now look up the hostname `web` or `db` and
 get back the appropriate container's IP address. For example, `web`'s
 application code could connect to the URL `postgres://db:5432` and start