update / phrasing

composer/content.md

@@ -10,15 +10,13 @@ You can read more about Composer in our [official documentation](https://getcomp
 
 ### Basic usage
 
-Running the `composer` image is as simple as follows:
-
 ```console
 $ docker run --rm --interactive --tty \
   --volume $PWD:/app \
-  %%IMAGE%% install
+  %%IMAGE%% <command>
 ```
 
-### Persistent cache / global configuration
+### Persist cache / global configuration
 
 You can bind mount the Composer home directory from your host to the container to enable a persistent cache or share global configuration:
 
@@ -26,12 +24,12 @@ You can bind mount the Composer home directory from your host to the container t
 $ docker run --rm --interactive --tty \
   --volume $PWD:/app \
   --volume ${COMPOSER_HOME:-$HOME/.composer}:/tmp \
-  %%IMAGE%% install
+  %%IMAGE%% <command>
 ```
 
 **Note:** this relies on the fact that the `COMPOSER_HOME` value is set to `/tmp` in the image by default.
 
-Or if you are following the XDG specification:
+Or if your environment follows the XDG specification:
 
 ```console
 $ docker run --rm --interactive --tty \
@@ -40,7 +38,7 @@ $ docker run --rm --interactive --tty \
   --volume ${COMPOSER_HOME:-$HOME/.config/composer}:$COMPOSER_HOME \
   --volume ${COMPOSER_CACHE_DIR:-$HOME/.cache/composer}:$COMPOSER_CACHE_DIR \
   --volume $PWD:/app \
-  %%IMAGE%% install
+  %%IMAGE%% <command>
 ```
 
 ### Filesystem permissions
@@ -51,9 +49,13 @@ By default, Composer runs as root inside the container. This can lead to permiss
 $ docker run --rm --interactive --tty \
   --volume $PWD:/app \
   --user $(id -u):$(id -g) \
-  %%IMAGE%% install
+  %%IMAGE%% <command>
 ```
 
+See: https://docs.docker.com/engine/reference/run/#user for details.
+
+> Note: Docker for Mac behaves differently and this tip might not apply to Docker for Mac users.
+
 ### Private repositories / SSH agent
 
 When you need to access private repositories, you will either need to share your configured credentials, or mount your `ssh-agent` socket inside the running container:
@@ -64,12 +66,12 @@ $ eval $(ssh-agent); \
   --volume $PWD:/app \
   --volume $SSH_AUTH_SOCK:/ssh-auth.sock \
   --env SSH_AUTH_SOCK=/ssh-auth.sock \
-  %%IMAGE%% install
+  %%IMAGE%% <command>
 ```
 
 **Note:** On OSX this requires Docker For Mac v2.2.0.0 or later, see [docker/for-mac#410](https://github.com/docker/for-mac/issues/410).
 
-When combining the use of private repositories with running Composer as another user, you might run into non-existent user errors (thrown by ssh). To work around this, simply mount the host passwd and group files (read-only) into the container:
+When combining the use of private repositories with running Composer as another user, you can run into non-existent user errors (thrown by ssh). To work around this, bind mount the host passwd and group files (read-only) into the container:
 
 ```console
 $ eval $(ssh-agent); \
@@ -80,7 +82,7 @@ $ eval $(ssh-agent); \
   --volume /etc/group:/etc/group:ro \
   --env SSH_AUTH_SOCK=/ssh-auth.sock \
   --user $(id -u):$(id -g) \
-  %%IMAGE%% install
+  %%IMAGE%% <command>
 ```
 
 # Troubleshooting
@@ -108,7 +110,7 @@ Suggestions:
 	  "config": {
 	    "platform": {
 	      "php": "MAJOR.MINOR.PATCH",
-	      "ext-something": "1"
+	      "ext-something": "MAJOR.MINOR.PATCH"
 	    }
 	  }
 	}