diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md
index 49a7497e2de6..f60f04ac2947 100644
--- a/docs/reference/commandline/run.md
+++ b/docs/reference/commandline/run.md
@@ -91,7 +91,7 @@ Create and run a new container from an image
 | `-P`, `--publish-all`                         |               |           | Publish all exposed ports to random ports                                                                                                                                                                                                                                                                        |
 | [`--pull`](#pull)                             | `string`      | `missing` | Pull image before running (`always`, `missing`, `never`)                                                                                                                                                                                                                                                         |
 | `-q`, `--quiet`                               |               |           | Suppress the pull output                                                                                                                                                                                                                                                                                         |
-| `--read-only`                                 |               |           | Mount the container's root filesystem as read only                                                                                                                                                                                                                                                               |
+| [`--read-only`](#read-only)                   |               |           | Mount the container's root filesystem as read only                                                                                                                                                                                                                                                               |
 | [`--restart`](#restart)                       | `string`      | `no`      | Restart policy to apply when a container exits                                                                                                                                                                                                                                                                   |
 | `--rm`                                        |               |           | Automatically remove the container when it exits                                                                                                                                                                                                                                                                 |
 | `--runtime`                                   | `string`      |           | Runtime to use for this container                                                                                                                                                                                                                                                                                |
@@ -118,14 +118,11 @@ Create and run a new container from an image
 
 ## Description
 
-The `docker run` command first `creates` a writeable container layer over the
-specified image, and then `starts` it using the specified command. That is,
-`docker run` is equivalent to the API `/containers/create` then
-`/containers/(id)/start`. A stopped container can be restarted with all its
-previous changes intact using `docker start`. See `docker ps -a` to view a list
-of all containers.
+The `docker run` command runs a command in a new container, pulling the image if needed and starting the container.
+
+You can restart a stopped container with all its previous changes intact using `docker start`.
+Use `docker ps -a` to view a list of all containers, including those that are stopped.
 
-For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/network/).
 
 ## Examples
 
@@ -144,9 +141,9 @@ d6c0fe130dba        debian:7            "/bin/bash"         26 seconds ago
 This example runs a container named `test` using the `debian:latest`
 image. The `-it` instructs Docker to allocate a pseudo-TTY connected to
 the container's stdin; creating an interactive `bash` shell in the container.
-In the example, the `bash` shell is quit by entering
-`exit 13`. This exit code is passed on to the caller of
-`docker run`, and is recorded in the `test` container's metadata.
+The example quits the `bash` shell by entering
+`exit 13`, passing the exit code on to the caller of
+`docker run`, and recording it in the `test` container's metadata.
 
 ### <a name="cidfile"></a> Capture container ID (--cidfile)
 
@@ -154,9 +151,9 @@ In the example, the `bash` shell is quit by entering
 $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
 ```
 
-This will create a container and print `test` to the console. The `cidfile`
+This creates a container and prints `test` to the console. The `cidfile`
 flag makes Docker attempt to create a new file and write the container ID to it.
-If the file exists already, Docker will return an error. Docker will close this
+If the file exists already, Docker returns an error. Docker closes this
 file when `docker run` exits.
 
 ### <a name="privileged"></a> Full container capabilities (--privileged)
@@ -167,9 +164,9 @@ root@bc338942ef20:/# mount -t tmpfs none /mnt
 mount: permission denied
 ```
 
-This will *not* work, because by default, most potentially dangerous kernel
-capabilities are dropped; including `cap_sys_admin` (which is required to mount
-filesystems). However, the `--privileged` flag will allow it to run:
+This *doesn't* work, because by default, Docker drops most potentially dangerous kernel
+capabilities, including `CAP_SYS_ADMIN ` (which is required to mount
+filesystems). However, the `--privileged` flag allows it to run:
 
 ```console
 $ docker run -t -i --privileged ubuntu bash
@@ -190,8 +187,8 @@ flag exists to allow special use-cases, like running Docker within Docker.
 $ docker  run -w /path/to/dir/ -i -t  ubuntu pwd
 ```
 
-The `-w` lets the command being executed inside directory given, here
-`/path/to/dir/`. If the path does not exist it is created inside the container.
+The `-w` option runs the command executed inside the directory specified, in this example,
+`/path/to/dir/`. If the path does not exist, Docker creates it inside the container.
 
 ### <a name="storage-opt"></a> Set storage driver options per container (--storage-opt)
 
@@ -199,14 +196,17 @@ The `-w` lets the command being executed inside directory given, here
 $ docker run -it --storage-opt size=120G fedora /bin/bash
 ```
 
-This (size) will allow to set the container filesystem size to 120G at creation time.
+This (size) constraints the container filesystem size to 120G at creation time.
 This option is only available for the `devicemapper`, `btrfs`, `overlay2`,
-`windowsfilter` and `zfs` graph drivers.
-For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers,
-user cannot pass a size less than the Default BaseFS Size.
+`windowsfilter` and `zfs` storage drivers.
+
 For the `overlay2` storage driver, the size option is only available if the
 backing filesystem is `xfs` and mounted with the `pquota` mount option.
-Under these conditions, user can pass any size less than the backing filesystem size.
+Under these conditions, you can pass any size less than the backing filesystem size.
+
+For the `windowsfilter`, `devicemapper`, `btrfs`, and `zfs` storage drivers,
+you cannot pass a size less than the Default BaseFS Size.
+
 
 ### <a name="tmpfs"></a> Mount tmpfs (--tmpfs)
 
@@ -217,32 +217,41 @@ $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image
 The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`,
 `noexec`, `nosuid`, `size=65536k` options.
 
-### <a name="volume"></a> Mount volume (-v, --read-only)
+### <a name="volume"></a> Mount volume (-v)
 
 ```console
-$ docker  run  -v `pwd`:`pwd` -w `pwd` -i -t  ubuntu pwd
+$ docker  run  -v $(pwd):$(pwd) -w $(pwd) -i -t  ubuntu pwd
 ```
 
-The `-v` flag mounts the current working directory into the container. The `-w`
-lets the command being executed inside the current working directory, by
-changing into the directory to the value returned by `pwd`. So this
-combination executes the command using the container, but inside the
-current working directory.
+The example above mounts the current directory into the container at the same path
+using the `-v` flag, sets it as the working directory, and then runs the `pwd` command inside the container.
+
+As of Docker Engine version 23, you can use relative paths on the host.
+
+```console
+$ docker  run  -v ./content:/content -w /content -i -t  ubuntu pwd
+```
+
+The example above mounts the `content` directory in the current directory into the container at the
+`/content` path using the `-v` flag, sets it as the working directory, and then
+runs the `pwd` command inside the container.
 
 ```console
 $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
 ```
 
 When the host directory of a bind-mounted volume doesn't exist, Docker
-will automatically create this directory on the host for you. In the
-example above, Docker will create the `/doesnt/exist`
+automatically creates this directory on the host for you. In the
+example above, Docker creates the `/doesnt/exist`
 folder before starting your container.
 
+### <a name="read-only"></a> Mount volume read-only (--read-only)
+
 ```console
 $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here
 ```
 
-Volumes can be used in combination with `--read-only` to control where
+You can use volumes in combination with the `--read-only` flag to control where
 a container writes files. The `--read-only` flag mounts the container's root
 filesystem as read only prohibiting writes to locations other than the
 specified volumes for the container.
@@ -256,7 +265,7 @@ binary (refer to [get the Linux binary](https://docs.docker.com/engine/install/b
 you give the container the full access to create and manipulate the host's
 Docker daemon.
 
-On Windows, the paths must be specified using Windows-style semantics.
+On Windows, you must specify the paths using Windows-style path semantics.
 
 ```powershell
 PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt
@@ -266,9 +275,9 @@ PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.
 Contents of file
 ```
 
-The following examples will fail when using Windows-based containers, as the
+The following examples fails when using Windows-based containers, as the
 destination of a volume or bind mount inside the container must be one of:
-a non-existing or empty directory; or a drive other than C:. Further, the source
+a non-existing or empty directory; or a drive other than `C:`. Further, the source
 of a bind mount must be a local directory, not a file.
 
 ```powershell
@@ -282,13 +291,12 @@ docker run -v c:\foo:c:\existing-directory-with-contents ...
 
 For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/storage/volumes/)
 
-
 ### <a name="mount"></a> Add bind mounts or volumes using the --mount flag
 
-The `--mount` flag allows you to mount volumes, host-directories and `tmpfs`
+The `--mount` flag allows you to mount volumes, host-directories, and `tmpfs`
 mounts in a container.
 
-The `--mount` flag supports most options that are supported by the `-v` or the
+The `--mount` flag supports most options supported by the `-v` or the
 `--volume` flag, but uses a different syntax. For in-depth information on the
 `--mount` flag, and a comparison between `--volume` and `--mount`, refer to
 [Bind mounts](https://docs.docker.com/storage/bind-mounts/).
@@ -314,10 +322,10 @@ $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash
 This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host
 machine. You can also specify `udp` and `sctp` ports.
 The [Docker User Guide](https://docs.docker.com/network/links/)
-explains in detail how to manipulate ports in Docker.
+explains in detail how to use ports in Docker.
 
 Note that ports which are not bound to the host (i.e., `-p 80:80` instead of
-`-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if
+`-p 127.0.0.1:80:80`) are externally accessible. This also applies if
 you configured UFW to block this specific port, as Docker manages its
 own iptables rules. [Read more](https://docs.docker.com/network/iptables/)
 
@@ -345,7 +353,7 @@ When creating (and running) a container from an image, the daemon checks if the
 image exists in the local image cache. If the image is missing, an error is
 returned to the CLI, allowing it to initiate a pull.
 
-The default (`missing`) is to only pull the image if it is not present in the
+The default (`missing`) is to only pull the image if it's not present in the
 daemon's image cache. This default allows you to run images that only exist
 locally (for example, images you built from a Dockerfile, but that have not
 been pushed to a registry), and reduces networking.
@@ -378,7 +386,7 @@ $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
 
 Use the `-e`, `--env`, and `--env-file` flags to set simple (non-array)
 environment variables in the container you're running, or overwrite variables
-that are defined in the Dockerfile of the image you're running.
+defined in the Dockerfile of the image you're running.
 
 You can define the variable and its value when running the container:
 
@@ -388,7 +396,7 @@ VAR1=value1
 VAR2=value2
 ```
 
-You can also use variables that you've exported to your local environment:
+You can also use variables exported to your local environment:
 
 ```console
 export VAR1=value1
@@ -402,7 +410,7 @@ VAR2=value2
 When running the command, the Docker CLI client checks the value the variable
 has in your local environment and passes it to the container.
 If no `=` is provided and that variable is not exported in your local
-environment, the variable won't be set in the container.
+environment, the variable isn't set in the container.
 
 You can also load the environment variables from a file. This file should use
 the syntax `<variable>=value` (which sets the variable to the given value) or
@@ -446,7 +454,7 @@ $ docker run --label-file ./labels ubuntu bash
 
 The label-file format is similar to the format for loading environment
 variables. (Unlike environment variables, labels are not visible to processes
-running inside a container.) The following example illustrates a label-file
+running inside a container.) The following example shows a label-file
 format:
 
 ```console
@@ -465,8 +473,9 @@ the Docker User Guide.
 
 ### <a name="network"></a> Connect a container to a network (--network)
 
-When you start a container use the `--network` flag to connect it to a network.
-The following commands create a network named `my-net`, and adds a `busybox` container
+To start a container and connect it to a network, use the `--network` option.
+
+The following commands create a network named `my-net` and adds a `busybox` container
 to the `my-net` network.
 
 ```console
@@ -484,7 +493,7 @@ $ docker run -itd --network=my-net --ip=10.10.9.75 busybox
 If you want to add a running container to a network use the `docker network connect` subcommand.
 
 You can connect multiple containers to the same network. Once connected, the
-containers can communicate easily using only another container's IP address
+containers can communicate using only another container's IP address
 or name. For `overlay` networks or custom plugins that support multi-host
 connectivity, containers connected to the same multi-host network but launched
 from different Engines can also communicate in this way.
@@ -498,6 +507,8 @@ from different Engines can also communicate in this way.
 You can disconnect a container from a network using the `docker network
 disconnect` command.
 
+For more information on connecting a container to a network when using the `run` command, see the ["*Docker network overview*"](https://docs.docker.com/network/).
+
 ### <a name="volumes-from"></a> Mount volumes from container (--volumes-from)
 
 ```console
@@ -505,13 +516,13 @@ $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ub
 ```
 
 The `--volumes-from` flag mounts all the defined volumes from the referenced
-containers. Containers can be specified by repetitions of the `--volumes-from`
+containers. You can specify more than one container by repetitions of the `--volumes-from`
 argument. The container ID may be optionally suffixed with `:ro` or `:rw` to
 mount the volumes in read-only or read-write mode, respectively. By default,
-the volumes are mounted in the same mode (read write or read only) as
+Docker mounts the volumes in the same mode (read write or read only) as
 the reference container.
 
-Labeling systems like SELinux require that proper labels are placed on volume
+Labeling systems like SELinux require placing proper labels on volume
 content mounted into a container. Without a label, the security system might
 prevent the processes running inside the container from using the content. By
 default, Docker does not change the labels set by the OS.
@@ -541,17 +552,17 @@ only to the container's `STDIN`.
 $ docker run -a stderr ubuntu echo test
 ```
 
-This isn't going to print anything unless there's an error because we've
-only attached to the `STDERR` of the container. The container's logs
-still store what's been written to `STDERR` and `STDOUT`.
+This isn't going to print anything to the console unless there's an error because output
+is only attached to the `STDERR` of the container. The container's logs
+still store what's written to `STDERR` and `STDOUT`.
 
 ```console
 $ cat somefile | docker run -i -a stdin mybuilder dobuild
 ```
 
-This is a way of using `--attach` to pipe a build file into a container.
-The container's ID will be printed after the build is done and the build
-logs could be retrieved using `docker logs`. This is
+This example shows a way of using `--attach` to pipe a file into a container.
+The command prints the container's ID after the build completes and you can retrieve
+the build logs using `docker logs`. This is
 useful if you need to pipe a file or something else into a container and
 retrieve the container's ID once the container has finished running.
 
@@ -571,15 +582,15 @@ brw-rw---- 1 root disk 8, 3 Feb  9 16:05 /dev/sdd
 crw-rw-rw- 1 root root 1, 5 Feb  9 16:05 /dev/foobar
 ```
 
-It is often necessary to directly expose devices to a container. The `--device`
-option enables that. For example, a specific block storage device or loop
-device or audio device can be added to an otherwise unprivileged container
+It's often necessary to directly expose devices to a container. The `--device`
+option enables that. For example, adding a specific block storage device or loop
+device or audio device to an otherwise unprivileged container
 (without the `--privileged` flag) and have the application directly access it.
 
-By default, the container will be able to `read`, `write` and `mknod` these devices.
+By default, the container is able to `read`, `write` and `mknod` these devices.
 This can be overridden using a third `:rwm` set of options to each `--device`
-flag. If the container is running in privileged mode, then the permissions specified
-will be ignored.
+flag. If the container is running in privileged mode, then Docker ignores the
+specified permissions.
 
 ```console
 $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk  /dev/xvdc
@@ -600,8 +611,8 @@ fdisk: unable to open /dev/xvdc: Operation not permitted
 
 > **Note**
 >
-> The `--device` option cannot be safely used with ephemeral devices. Block devices
-> that may be removed should not be added to untrusted containers with `--device`.
+> The `--device` option cannot be safely used with ephemeral devices. You shouldn't 
+> add block devices that may be removed to untrusted containers with `--device`.
 
 For Windows, the format of the string passed to the `--device` option is in
 the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019
@@ -612,8 +623,8 @@ Refer to the table defined in the [Windows container
 docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers)
 for a list of container-supported device interface class GUIDs.
 
-If this option is specified for a process-isolated Windows container, _all_
-devices that implement the requested device interface class GUID are made
+If you specify this option for a process-isolated Windows container, Docker makes
+_all_ devices that implement the requested device interface class GUID
 available in the container. For example, the command below makes all COM
 ports on the host visible in the container.
 
@@ -628,16 +639,16 @@ PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.micro
 
 ### <a name="device-cgroup-rule"></a> Using dynamically created devices (--device-cgroup-rule)
 
-Devices available to a container are assigned at creation time. The
-assigned devices will both be added to the cgroup.allow file and
-created into the container once it is run. This poses a problem when
-a new device needs to be added to running container.
+Docker assigns devices available to a container at creation time. The
+assigned devices are added to the cgroup.allow file and
+created into the container when it runs. This poses a problem when
+you need to add a new device to running container.
 
-One of the solutions is to add a more permissive rule to a container
+One solution is to add a more permissive rule to a container
 allowing it access to a wider range of devices. For example, supposing
-our container needs access to a character device with major `42` and
-any number of minor number (added as new devices appear), the
-following rule would be added:
+the container needs access to a character device with major `42` and
+any number of minor numbers (added as new devices appear), add the
+following rule:
 
 ```console
 $ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image
@@ -646,18 +657,19 @@ $ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image
 Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>`
 the required device when it is added.
 
-> **Note**: initially present devices still need to be explicitly added to the
+> **Note**: You still need to explicitly add initially present devices to the
 > `docker run` / `docker create` command.
 
 ### <a name="gpus"></a> Access an NVIDIA GPU
 
 The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to
-install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).
-Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/)
+install the [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).
+
+Read [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/)
 for more information.
 
-To use `--gpus`, specify which GPUs (or all) to use. If no value is provided, all
-available GPUs are used. The example below exposes all available GPUs.
+To use `--gpus`, specify which GPUs (or all) to use. If you provide no value, Docker uses all
+available GPUs. The example below exposes all available GPUs.
 
 ```console
 $ docker run -it --rm --gpus all ubuntu nvidia-smi
@@ -678,7 +690,7 @@ $ docker run -it --rm --gpus '"device=0,2"' nvidia-smi
 
 ### <a name="restart"></a> Restart policies (--restart)
 
-Use Docker's `--restart` to specify a container's *restart policy*. A restart
+Use the `--restart` flag to specify a container's *restart policy*. A restart
 policy controls whether the Docker daemon restarts a container after exit.
 Docker supports the following restart policies:
 
@@ -686,17 +698,17 @@ Docker supports the following restart policies:
 |:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `no`                       | Do not automatically restart the container when it exits. This is the default.                                                                                                                                                                                   |
 | `on-failure[:max-retries]` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts.                                                                                                                     |
-| `unless-stopped`           | Restart the container unless it is explicitly stopped or Docker itself is stopped or restarted.                                                                                                                                                                  |
-| `always`                   | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. |
+| `unless-stopped`           | Restart the container unless it's explicitly stopped or Docker itself is stopped or restarted.                                                                                                                                                                  |
+| `always`                   | Always restart the container regardless of the exit status. When you specify always, the Docker daemon tries to restart the container indefinitely. The container always starts on daemon startup, regardless of the current state of the container. |
 
 ```console
 $ docker run --restart=always redis
 ```
 
 This will run the `redis` container with a restart policy of **always**
-so that if the container exits, Docker will restart it.
+so that if the container exits, Docker restarts it.
 
-More detailed information on restart policies can be found in the
+You can find more detailed information on restart policies in the
 [Restart Policies (--restart)](../run.md#restart-policies---restart)
 section of the Docker run reference page.
 
@@ -742,8 +754,8 @@ for the bridge device).
 
 Since setting `ulimit` settings in a container requires extra privileges not
 available in the default container, you can set these using the `--ulimit` flag.
-`--ulimit` is specified with a soft and hard limit as such:
-`<type>=<soft limit>[:<hard limit>]`, for example:
+Specify `--ulimit` with a soft and hard limit in the format
+`<type>=<soft limit>[:<hard limit>]`. For example:
 
 ```console
 $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
@@ -752,21 +764,25 @@ $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
 
 > **Note**
 >
-> If you do not provide a `hard limit`, the `soft limit` is used
-> for both values. If no `ulimits` are set, they are inherited from
-> the default `ulimits` set on the daemon. The `as` option is disabled now.
+> If you don't provide a hard limit value, Docker uses the soft limit value
+> for both values. If you don't provide any values, they are inherited from
+> the default `ulimits` set on the daemon.
+
+> **Note**
+>
+> The `as` option is deprecated.
 > In other words, the following script is not supported:
 >
 > ```console
 > $ docker run -it --ulimit as=1024 fedora /bin/bash
 > ```
 
-The values are sent to the appropriate `syscall` as they are set.
-Docker doesn't perform any byte conversion. Take this into account when setting the values.
+Docker sends the values to the appropriate OS `syscall` and doesn't perform any byte conversion.
+Take this into account when setting the values.
 
 #### For `nproc` usage
 
-Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the
+Be careful setting `nproc` with the `ulimit` flag as Linux uses `nproc` to set the
 maximum number of processes available to a user, not to a container. For example, start four
 containers with `daemon` user:
 
@@ -780,36 +796,36 @@ $ docker run -d -u daemon --ulimit nproc=3 busybox top
 $ docker run -d -u daemon --ulimit nproc=3 busybox top
 ```
 
-The 4th container fails and reports "[8] System error: resource temporarily unavailable" error.
+The 4th container fails and reports a "[8] System error: resource temporarily unavailable" error.
 This fails because the caller set `nproc=3` resulting in the first three containers using up
 the three processes quota set for the `daemon` user.
 
 ### <a name="stop-signal"></a> Stop container with signal (--stop-signal)
 
-The `--stop-signal` flag sets the system call signal that will be sent to the
+The `--stop-signal` flag sends the system call signal to the
 container to exit. This signal can be a signal name in the format `SIG<NAME>`,
 for instance `SIGKILL`, or an unsigned number that matches a position in the
 kernel's syscall table, for instance `9`.
 
-The default is defined by [`STOPSIGNAL`](https://docs.docker.com/engine/reference/builder/#stopsignal)
+The default value is defined by [`STOPSIGNAL`](https://docs.docker.com/engine/reference/builder/#stopsignal)
 in the image, or `SIGTERM` if the image has no `STOPSIGNAL` defined.
 
 ### <a name="security-opt"></a> Optional security options (--security-opt)
 
-On Windows, this flag can be used to specify the `credentialspec` option.
+On Windows, you can use this flag to specify the `credentialspec` option.
 The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`.
 
 ### <a name="stop-timeout"></a> Stop container with timeout (--stop-timeout)
 
 The `--stop-timeout` flag sets the number of seconds to wait for the container
 to stop after sending the pre-defined (see `--stop-signal`) system call signal.
-If the container does not exit after the timeout elapses, it is forcibly killed
+If the container does not exit after the timeout elapses, it's forcibly killed
 with a `SIGKILL` signal.
 
-If `--stop-timeout` is set to `-1`, no timeout is applied, and the daemon will
-wait indefinitely for the container to exit.
+If you set `--stop-timeout` to `-1`, no timeout is applied, and the daemon
+waits indefinitely for the container to exit.
 
-The default is determined by the daemon, and is 10 seconds for Linux containers,
+The Daemon determines the default, and is 10 seconds for Linux containers,
 and 30 seconds for Windows containers.
 
 ### <a name="isolation"></a> Specify isolation technology for container (--isolation)
@@ -857,12 +873,12 @@ PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hy
 
 ### <a name="memory"></a> Specify hard limits on memory available to containers (-m, --memory)
 
-These parameters always set an upper limit on the memory available to the container. On Linux, this
-is set on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`.
+These parameters always set an upper limit on the memory available to the container. Linux sets this
+on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`.
 
-On Windows, this will affect containers differently depending on what type of isolation is used.
+On Windows, this affects containers differently depending on what type of isolation you use.
 
-- With `process` isolation, Windows will report the full memory of the host system, not the limit to applications running inside the container
+- With `process` isolation, Windows reports the full memory of the host system, not the limit to applications running inside the container
 
     ```powershell
     PS C:\> docker run -it -m 2GB --isolation=process microsoft/nanoserver powershell Get-ComputerInfo *memory*
@@ -877,7 +893,7 @@ On Windows, this will affect containers differently depending on what type of is
     OsMaxProcessMemorySize     : 137438953344
     ```
 
-- With `hyperv` isolation, Windows will create a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory."
+- With `hyperv` isolation, Windows creates a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory."
 
     ```powershell
     PS C:\> docker run -it -m 2GB --isolation=hyperv microsoft/nanoserver powershell Get-ComputerInfo *memory*
@@ -892,7 +908,6 @@ On Windows, this will affect containers differently depending on what type of is
     OsMaxProcessMemorySize     : 137438953344
     ```
 
-
 ### <a name="sysctl"></a> Configure namespaced kernel parameters (sysctls) at runtime (--sysctl)
 
 The `--sysctl` sets namespaced kernel parameters (sysctls) in the
@@ -909,6 +924,7 @@ $ docker run --sysctl net.ipv4.ip_forward=1 someimage
 > inside of a container that also modify the host system. As the kernel
 > evolves we expect to see more sysctls become namespaced.
 
+
 #### Currently supported sysctls
 
 IPC Namespace:
@@ -922,3 +938,13 @@ Network Namespace:
 
 - Sysctls beginning with `net.*`
 - If you use the `--network=host` option using these sysctls are not allowed.
+
+## Command internals
+
+The `docker run` command is equivalent to the following API calls:
+
+- `/<API version>/containers/create`
+  - If that call returns a 404 (image not found), and depending on the `--pull` option ("always", "missing", "never") the call can trigger a `docker pull <image>`.
+- `/containers/create` again after pulling the image.
+- `/containers/(id)/start` to start the container.
+- `/containers/(id)/attach` to attach to the container when starting with the `-it` flags for interactive containers.
\ No newline at end of file