diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md
index 792b845c3f..349ab95006 100644
--- a/compose/compose-file/compose-file-v2.md
+++ b/compose/compose-file/compose-file-v2.md
@@ -423,7 +423,7 @@ An entry with the ip address and hostname will be created in `/etc/hosts` inside
 
 ### group_add
 
-> [Version 2 file format](compose-versioning.md#version-2) and up.
+> [Version 2 file format](compose-versioning.md#version-2) only.
 
 Specify additional groups (by name or number) which the user inside the
 container will be a member of. Groups must exist in both the container and the
@@ -436,11 +436,14 @@ details.
 
 A full example:
 
-    version: '2'
-    services:
-        image: alpine
-        group_add:
-          - mail
+```
+version: '2'
+services:
+  myservice:
+    image: alpine
+    group_add:
+      - mail
+```
 
 Running `id` inside the created container will show that the user belongs to
 the `mail` group, which would not have been the case if `group_add` were not
diff --git a/compose/compose-file/compose-versioning.md b/compose/compose-file/compose-versioning.md
index 677a8c84c4..a7b3ba03b0 100644
--- a/compose/compose-file/compose-versioning.md
+++ b/compose/compose-file/compose-versioning.md
@@ -190,7 +190,7 @@ Designed to be cross-compatible between Compose and the Docker Engine's
 several more.
 
 - Removed: `volume_driver`, `volumes_from`, `cpu_shares`, `cpu_quota`, `cpuset`,
-  `mem_limit`, `memswap_limit`. See the [upgrading](#upgrading)
+  `mem_limit`, `memswap_limit`, `extends`, `group_add`. See the [upgrading](#upgrading)
   guide for how to migrate away from these.
 
 - Added: [deploy](index.md#deploy)
@@ -228,6 +228,7 @@ several options have been removed:
     `docker stack deploy`, and is ignored by `docker-compose`.
 
 -   `extends`: This option has been removed for `version: "3.x"` Compose files.
+-   `group_add`: This option has been removed for `version: "3.x"` Compose files.
 
 ### Version 1 to 2.x
 
diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md
index ac8a056d03..ccecaeb9c0 100644
--- a/compose/compose-file/index.md
+++ b/compose/compose-file/index.md
@@ -25,9 +25,9 @@ a section in the configuration file such as `build`, `deploy`, `depends_on`,
 sub-topics. This maps to the `<key>: <option>: <value>` indent structure of the
 Compose file.
 
-The best way to quickly grok the layout and syntax of a Compose file is to 
+The best way to quickly grok the layout and syntax of a Compose file is to
 read [Get started with Docker Compose](/compose/gettingstarted/) and to look
-at files for [applications on GitHub](https://github.com/search?q=in%3Apath+docker-compose.yml+extension%3Ayml&type=Code). 
+at files for [applications on GitHub](https://github.com/search?q=in%3Apath+docker-compose.yml+extension%3Ayml&type=Code).
 A good place to start is the
 version 3 Compose stack file we use for the voting app sample to illustrate
 multi-container apps, service definitions, swarm mode, the `deploy` key, and the
@@ -654,31 +654,6 @@ An entry with the ip address and hostname will be created in `/etc/hosts` inside
     162.242.195.82  somehost
     50.31.209.229   otherhost
 
-### group_add
-
-> [Version 2 file format](compose-versioning.md#version-2) and up.
-
-Specify additional groups (by name or number) which the user inside the
-container will be a member of. Groups must exist in both the container and the
-host system to be added. An example of where this is useful is when multiple
-containers (running as different users) need to all read or write the same
-file on the host system. That file can be owned by a group shared by all the
-containers, and specified in `group_add`. See the
-[Docker documentation](/engine/reference/run.md#additional-groups) for more
-details.
-
-A full example:
-
-    version: '2'
-    services:
-        image: alpine
-        group_add:
-          - mail
-
-Running `id` inside the created container will show that the user belongs to
-the `mail` group, which would not have been the case if `group_add` were not
-used.
-
 ### healthcheck
 
 > [Version 2.1 file format](compose-versioning.md#version-21) and up.
@@ -1489,7 +1464,7 @@ Compose. `docker-compose up` will not attempt to create it, and will raise
 an error if it doesn't exist.
 
 `external` cannot be used in conjunction with other network configuration keys
-(`driver`, `driver_opts`, `group_add`, `ipam`, `internal`).
+(`driver`, `driver_opts`, `ipam`, `internal`).
 
 In the example below, `proxy` is the gateway to the outside world. Instead of
 attempting to create a network called `[projectname]_outside`, Compose will