emphasis on recommended solutions

composer/content.md

@@ -23,7 +23,8 @@ $ docker run --rm --interactive --tty \
 You can bind mount the Composer home directory from your host to the container to enable a persistent cache or share global configuration:
 
 ```console
-$ docker run --rm --interactive --tty \
+$ COMPOSER_HOME=$HOME/.composer \
+  docker run --rm --interactive --tty \
   --volume $PWD:/app \
   --volume $COMPOSER_HOME:/tmp \
   %%IMAGE%% install
@@ -85,48 +86,39 @@ $ docker run --rm --interactive --tty \
 
 # Troubleshooting
 
-### PHP versions
+### PHP version & extensions
+
+Our image is aimed at quickly running Composer without the need for having a PHP runtime installed on your host. You should not rely on the PHP version in our container. We do not provide a Composer image for each supported PHP version because we do not want to encourage using Composer as a base image or a production image.
 
-Our image is aimed at quickly running Composer without the need for having a PHP runtime installed. You should not rely on the PHP version in our container. We do not provide a Composer image for each supported PHP version because we do not want to encourage using Composer as a base image or a production image.
+We try to deliver an image that is as lean as possible, built for running Composer only. Sometimes dependencies or Composer [scripts](https://getcomposer.org/doc/articles/scripts.md) require the availability of certain PHP extensions.
 
 Suggestions:
 
--	use [`--ignore-platform-reqs`](https://getcomposer.org/doc/03-cli.md#install-i):
+-	(optimal) create your own build image and [install](https://getcomposer.org/doc/faqs/how-to-install-composer-programmatically.md) Composer inside it.
 
-	```console
-	$ composer install --ignore-platform-reqs
+	**Note:** Docker 17.05 introduced [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/), simplifying this enormously:
+
+	```dockerfile
+	COPY --from=%%IMAGE%% /usr/bin/composer /usr/bin/composer
 	```
 
--	specify the target [platform](https://getcomposer.org/doc/06-config.md#platform) in your `composer.json`:
+-	(alternatively) specify the target [platform](https://getcomposer.org/doc/06-config.md#platform) / extension(s) in your `composer.json`:
 
 	```json
 	{
 	  "config": {
 	    "platform": {
-	      "php": "7.1.3"
+	      "php": "MAJOR.MINOR.PATCH",
+	      "ext-something": "1"
 	    }
 	  }
 	}
 	```
 
-### PHP extensions
-
-We aim to deliver an image that is as lean as possible, built for running Composer only. Sometimes dependencies or Composer [scripts](https://getcomposer.org/doc/articles/scripts.md) require the availability of certain PHP extensions.
-
-Suggestions:
-
--	pass the `--ignore-platform-reqs` and / or `--no-scripts` flags to `install` or `update`:
+-	(discouraged) pass the [`--ignore-platform-reqs`](https://getcomposer.org/doc/03-cli.md#install-i) and / or `--no-scripts` flags to `install` or `update`:
 
 	```console
 	$ docker run --rm --interactive --tty \
 	  --volume $PWD:/app \
 	  %%IMAGE%% install --ignore-platform-reqs --no-scripts
 	```
-
--	create your own buid image and [install](https://getcomposer.org/doc/faqs/how-to-install-composer-programmatically.md) Composer inside it.
-
-	**Note:** Docker 17.05 introduced [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/), simplifying this enormously:
-
-	```dockerfile
-	COPY --from=%%IMAGE%% /usr/bin/composer /usr/bin/composer
-	```

composer/maintainer.md

@@ -1 +1 @@
-[Composer](%%GITHUB-REPO%%)
+[Rob Bast](https://github.com/alcohol), with [contributions](%%GITHUB-REPO%%/graphs/contributors) from the community.