diff --git a/docs/reference/up.md b/docs/reference/up.md
index 0a1cecff1..8fe4fad5c 100644
--- a/docs/reference/up.md
+++ b/docs/reference/up.md
@@ -20,9 +20,10 @@ Options:
                        print new container names.
 --no-color             Produce monochrome output.
 --no-deps              Don't start linked services.
---x-smart-recreate     Only recreate containers whose configuration or
-                       image needs to be updated. (EXPERIMENTAL)
+--force-recreate       Recreate containers even if their configuration and
+                       image haven't changed. Incompatible with --no-recreate.
 --no-recreate          If containers already exist, don't recreate them.
+                       Incompatible with --force-recreate.
 --no-build             Don't build an image, even if it's missing
 -t, --timeout TIMEOUT  Use this timeout in seconds for container shutdown
                        when attached or when containers are already
@@ -31,12 +32,17 @@ Options:
 
 Builds, (re)creates, starts, and attaches to containers for a service.
 
-Linked services will be started, unless they are already running.
+Unless they are already running, this command also starts any linked services.
 
-By default, `docker-compose up` will aggregate the output of each container and,
-when it exits, all containers will be stopped. Running `docker-compose up -d`,
-will start the containers in the background and leave them running.
+The `docker-compose up` command aggregates the output of each container. When
+the command exits, all containers are stopped. Running `docker-compose up -d`
+starts the containers in the background and leaves them running.
 
-By default, if there are existing containers for a service, `docker-compose up` will stop and recreate them (preserving mounted volumes with [volumes-from]), so that changes in `docker-compose.yml` are picked up. If you do not want containers stopped and recreated, use `docker-compose up --no-recreate`. This will still start any stopped containers, if needed.
+If there are existing containers for a service, and the service's configuration
+or image was changed after the container's creation, `docker-compose up` picks
+up the changes by stopping and recreating the containers (preserving mounted
+volumes). To prevent Compose from picking up changes, use the `--no-recreate`
+flag.
 
-[volumes-from]: http://docs.docker.io/en/latest/use/working_with_volumes/
+If you want to force Compose to stop and recreate all containers, use the
+`--force-recreate` flag.