ENGDOCS-1989 (#19416)

* ENGDOCS-1989

* realistic example

* realistic example

content/compose/multiple-compose-files/extends.md

@@ -24,12 +24,14 @@ are relative to the base Compose file. This is required because extend files
 need not be valid Compose files. Extend files can contain small fragments of
 configuration. Tracking which fragment of a service is relative to which path is
 difficult and confusing, so to keep paths easier to understand, all paths must
-be defined relative to the base file. { .important }
+be defined relative to the base file. 
+{ .important }
 
 ## How it works
 
-When defining any service in your `compose.yaml` file, you can declare that you
-are extending another service:
+### Extending services from another file
+
+Take the following example:
 
 ```yaml
 services:
@@ -39,8 +41,10 @@ services:
       service: webapp
 ```
 
-This instructs Compose to re-use the configuration for the `webapp` service
-defined in the `common-services.yaml` file. Suppose that `common-services.yaml`
+This instructs Compose to re-use only the properties of the `webapp` service
+defined in the `common-services.yaml` file. The `webapp` service itself is not part of the final project.
+
+If `common-services.yaml`
 looks like this:
 
 ```yaml
@@ -52,11 +56,44 @@ services:
     volumes:
       - "/data"
 ```
-
-In this case, you get exactly the same result as if you wrote
+You get exactly the same result as if you wrote
 `docker-compose.yml` with the same `build`, `ports` and `volumes` configuration
 values defined directly under `web`.
 
+To include the service `webapp` in the final project when extending services from another file, you need to explicitly include both services in your current Compose file. For example (note this is a non-normative example):
+
+```yaml
+services:
+  web:
+    build: alpine
+    command: echo
+    extends:
+      file: common-services.yml
+      service: webapp
+  webapp:
+    extends:
+      file: common-services.yml
+      service: webapp
+```
+
+Alternatively, you can use [include](include.md). 
+
+### Extending services within the same file 
+
+If you define services in the same Compose file and extend one service from another, both the original service and the extended service will be part of your final configuration. For example:
+
+```yaml 
+services:
+  web:
+    build: alpine
+    extends: webapp
+  webapp:
+    environment:
+      - DEBUG=1
+```
+
+### Extending services within the same file and from another file
+
 You can go further and define, or re-define, configuration locally in
 `compose.yaml`:
 
@@ -75,23 +112,6 @@ services:
     cpu_shares: 10
 ```
 
-You can also write other services and link your `web` service to them:
-
-```yaml
-services:
-  web:
-    extends:
-      file: common-services.yml
-      service: webapp
-    environment:
-      - DEBUG=1
-    cpu_shares: 5
-    depends_on:
-      - db
-  db:
-    image: postgres
-```
-
 ## Further examples
 
 ### Example one