diff --git a/compose/reference/scale.md b/compose/reference/scale.md
index 8cee2797ec..2173ee45b4 100644
--- a/compose/reference/scale.md
+++ b/compose/reference/scale.md
@@ -5,6 +5,9 @@ title: docker-compose scale
 notoc: true
 ---
 
+> **Note**: This command is deprecated. Use the [up](up.md) command with the
+  `--scale` flag instead.
+
 ```
 Usage: scale [SERVICE=NUM...]
 ```
diff --git a/compose/reference/up.md b/compose/reference/up.md
index 3e43260d2b..32ee10e67c 100644
--- a/compose/reference/up.md
+++ b/compose/reference/up.md
@@ -6,7 +6,7 @@ notoc: true
 ---
 
 ```
-Usage: up [options] [SERVICE...]
+Usage: up [options] [--scale SERVICE=NUM...] [SERVICE...]
 
 Options:
     -d                         Detached mode: Run containers in the background,
@@ -30,6 +30,8 @@ Options:
                                the Compose file
     --exit-code-from SERVICE   Return the exit code of the selected service container.
                                Implies --abort-on-container-exit.
+    --scale SERVICE=NUM        Scale SERVICE to NUM instances. Overrides the `scale`
+                               setting in the Compose file if present.
 ```
 
 Builds, (re)creates, starts, and attaches to containers for a service.