From 6d32e6e94033ab657c047af9c043ff78dd1c779c Mon Sep 17 00:00:00 2001
From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
Date: Wed, 21 Feb 2024 08:55:49 +0000
Subject: [PATCH] ENGDOCS-1993 (#19441)

* ENGDOCS-1993

* improve reset  and override example
---
 content/compose/compose-file/05-services.md |  2 +-
 content/compose/compose-file/13-merge.md    | 68 +++++++++++----------
 2 files changed, 38 insertions(+), 32 deletions(-)

diff --git a/content/compose/compose-file/05-services.md b/content/compose/compose-file/05-services.md
index 9af8967cd0..4b4439b364 100644
--- a/content/compose/compose-file/05-services.md
+++ b/content/compose/compose-file/05-services.md
@@ -1151,7 +1151,7 @@ There is a performance penalty for applications that swap memory to disk often.
 
 - `none`: Turns off all container networking.
 - `host`: Gives the container raw access to the host's network interface.
-- `service:{name}`: Gives the containers access to the specified service only.
+- `service:{name}`: Gives the containers access to the specified service only. For more information, see [Container networks](../../network/_index.md#container-networks).
 
 ```yml
     network_mode: "host"
diff --git a/content/compose/compose-file/13-merge.md b/content/compose/compose-file/13-merge.md
index 7cb1cd4b69..94d2c69af1 100644
--- a/content/compose/compose-file/13-merge.md
+++ b/content/compose/compose-file/13-merge.md
@@ -145,41 +145,35 @@ For readability, it is recommended to explicitly set the attribute value to the
 array `[]` (with `!reset null` or `!reset []`) so that it is clear that resulting attribute will be
 cleared.
 
-Merging the following example YAML trees:
+A base `compose.yaml` file:
 
 ```yaml
 services:
-  foo:
-    build: 
-      dockerfile: foo.Dockerfile
-    read_only: true
-    environment:
-      FOO: BAR
+  app:
+    image: myapp
     ports:
-      - "8080:80"            
+      - "8080:80" 
+    environment:
+      FOO: BAR           
 ```
 
+And an `overide.compose.yaml` file:
+
 ```yaml
 services:
-  foo:
-    image: foo
-    build: !reset null
-    read_only: !reset false
+  app:
+    image: myapp
+    ports: !reset []
     environment:
       FOO: !reset null
-    ports: !reset []
 ```
 
-Result in a Compose application model equivalent to the YAML tree:
+Results in:
 
 ```yaml
 services:
-  foo:
-    image: foo
-    build: null
-    read_only: false
-    environment: {}
-    ports: []
+  app:
+    image: myapp
 ```
 
 ### Replace value
@@ -189,24 +183,36 @@ services:
 While `!reset` can be used to remove a declaration from a Compose file using an override file, `!override` allows you 
 to fully replace an attribute, bypassing the standard merge rules. A typical example is to fully replace a resource definition, to rely on a distinct model but using the same name.
 
-Merging the following example YAML trees:
+A base `compose.yaml` file:
 
 ```yaml
-networks:
-  foo:
-    # this is production configuration
-    name: production-overlay-network
-    driver: overlay
-    driver-opts: (...)
+services:
+  app:
+    image: myapp
+    ports:
+      - "8080:80"            
 ```
 
+To remove the original port, but expose a new one, the following override file is used:
+
 ```yaml
-networks:
-  # this is development configuration
-  foo: !override {}
+services:
+  app:
+    ports: !override
+      - "8443:443" 
 ```
 
-Results in a Compose application model equivalent to the override YAML tree.
+This results in: 
+
+```yaml
+services:
+  app:
+    image: myapp
+    ports:
+      - "8443:443" 
+```
+
+If `!override` had not been used, both `8080:80` and `8443:443` would be exposed as per the [merging rules outlined above](#sequence). 
 
 ## Additional resources