diff --git a/_data/toc.yaml b/_data/toc.yaml
index f9933c7ba5..6e915d67b0 100644
--- a/_data/toc.yaml
+++ b/_data/toc.yaml
@@ -1516,6 +1516,8 @@ manuals:
       title: Manage nodes in a swarm
     - path: /engine/swarm/services/
       title: Deploy services to a swarm
+    - path: /engine/swarm/stack-deploy/
+      title: Deploy a stack to a swarm
     - path: /engine/swarm/configs/
       title: Store service configuration data
     - path: /engine/swarm/secrets/
diff --git a/_includes/swarm-compose-compat.md b/_includes/swarm-compose-compat.md
new file mode 100644
index 0000000000..d9c41f0bc7
--- /dev/null
+++ b/_includes/swarm-compose-compat.md
@@ -0,0 +1,10 @@
+> **Note**
+>
+> The `docker stack deploy` command uses the legacy
+> [Compose file version 3](/compose/compose-file/compose-file-v3/)
+> format, used by Compose V1. The latest format, defined by the
+> [Compose specification](/compose/compose-file/)
+> isn't compatible with the `docker stack deploy` command.
+>
+> For more information about the evolution of Compose, see
+> [History of Compose](/compose/history/).
diff --git a/_includes/swarm-mode.md b/_includes/swarm-mode.md
new file mode 100644
index 0000000000..c1485d4c8c
--- /dev/null
+++ b/_includes/swarm-mode.md
@@ -0,0 +1,10 @@
+> **Note**
+>
+> Swarm mode is an advanced feature for managing a cluster of Docker daemons.
+>
+> Use Swarm mode if you intend to use Swarm as a production runtime environment.
+> 
+> If you're not planning on deploying with Swarm, use
+> [Docker Compose](/compose/) instead.
+> If you're developing for a Kubernetes deployment, consider using the
+> [integrated Kubernetes feature](/desktop/kubernetes/) in Docker Desktop.
diff --git a/engine/swarm/index.md b/engine/swarm/index.md
index 88f022eda3..4eee0cdf36 100644
--- a/engine/swarm/index.md
+++ b/engine/swarm/index.md
@@ -45,6 +45,8 @@ redirect_from:
 - /swarm/swarm_at_scale/troubleshoot/
 ---
 
+{% include swarm-mode.md %}
+
 To use Docker in swarm mode, install Docker. See
 [installation instructions](../../get-docker.md) for all operating systems and platforms.
 
diff --git a/engine/swarm/stack-deploy.md b/engine/swarm/stack-deploy.md
index f4cd9b88ab..5d3488fb5e 100644
--- a/engine/swarm/stack-deploy.md
+++ b/engine/swarm/stack-deploy.md
@@ -8,8 +8,10 @@ When running Docker Engine in swarm mode, you can use `docker stack deploy` to
 deploy a complete application stack to the swarm. The `deploy` command accepts
 a stack description in the form of a [Compose file](../../compose/compose-file/compose-file-v3.md).
 
-The `docker stack deploy` command supports any Compose file of version "3.0" or
-above. If you have an older version, see the [upgrade guide](../../compose/compose-file/compose-versioning.md#upgrading).
+{% include swarm-compose-compat.md %}
+
+The `docker stack deploy` command supports any Compose file of version "3.x".
+If you have an older version, see the [upgrade guide](../../compose/compose-file/compose-versioning.md#upgrading).
 
 To run through this tutorial, you need:
 
diff --git a/get-started/swarm-deploy.md b/get-started/swarm-deploy.md
index 1972a3b6b6..ec4dde5ee1 100644
--- a/get-started/swarm-deploy.md
+++ b/get-started/swarm-deploy.md
@@ -6,6 +6,8 @@ redirect_from:
 - /get-started/part4/
 ---
 
+{% include swarm-mode.md %}
+
 ## Prerequisites
 
 - Download and install Docker Desktop as described in [Get Docker](../get-docker.md).
@@ -26,6 +28,8 @@ Swarm never creates individual containers like we did in the previous step of th
 
 Let's write a simple stack file to run and manage our Todo app, the container `getting-started` image created in [Part 2](02_our_app.md) of the Quickstart tutorial. Place the following in a file called `bb-stack.yaml`:
 
+{% include swarm-compose-compat.md %}
+
 ```yaml
 version: '3.7'