readme: Tidy and add docs link

Signed-off-by: Christopher Crone <[email protected]>
Signed-off-by: Nicolas De Loof <[email protected]>

ecs/README.md

@@ -2,21 +2,34 @@
 
 ## Status
 
-:exclamation: The Docker ECS plugin is still in Beta. It's design and UX will evolve until 1.0 Final release.
+:exclamation: The Docker ECS plugin is still in Beta.
+Its design and UX will evolve until 1.0 Final release.
 
-## Example
+## Example and documentation
 
 You can find an application for testing this in [example](./example).
 
+You can find more documentation about using the Docker ECS integration
+[here](https://docs.docker.com/engine/context/ecs-integration/).
+
 ## Architecture
 
-ECS plugin is a [Docker CLI plugin](https://docs.docker.com/engine/extend/cli_plugins/)
-root command `ecs` require aws profile to get API credentials from `~/.aws/credentials`
-as well as AWS region - those will later be stored in a docker context
+The Docker ECS integration is a
+[Docker CLI plugin](https://docs.docker.com/engine/extend/cli_plugins/)
+with the root command of `ecs`.
+It requires an AWS profile to select the AWS API credentials from
+`~/.aws/credentials` as well as an AWS region. You can read more about CLI AWS
+credential management
+[here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
+Once setup, the AWS profile and region are stored in a Docker context.
+
+A `compose.yaml` file is parsed and converted into a
+[CloudFormation](https://aws.amazon.com/cloudformation/) template,
+which is then used to create all application resources in dependent order.
+Resources are cleaned up with the `down` command or in the case of a deployment
+failure.
 
-A `compose.yaml` is parsed and converted into a [CloudFormation](https://aws.amazon.com/cloudformation/)
-template, which will create all resources in dependent order and cleanup on
-`down` command or deployment failure.
+The architecture of the ECS integration is shown below:
 
 ```
   +--------------------------------------+
@@ -24,48 +37,61 @@ template, which will create all resources in dependent order and cleanup on
   +--------------------------------------+
 - Load
   +--------------------------------------+
-  | compose Model                        |
+  | Compose Model                        |
   +--------------------------------------+
 - Validate
   +--------------------------------------+
-  | compose Model suitable for ECS       |
+  | Compose Model suitable for ECS       |
   +--------------------------------------+
 - Convert
   +--------------------------------------+
   | CloudFormation Template              |
   +--------------------------------------+
 - Apply
-  +--------------+      +----------------+  
+  +--------------+      +----------------+
   | AWS API      |  or  | stack file     |
   +--------------+      +----------------+
 ```
 
-* _Load_ phase relies on [compose-go](https://github.com/compose-spec/compose-go). Any generic code we write for this 
-purpose should be proposed upstream.
-* _Validate_ phase is responsible to inject sane ECS defaults into the compose-go model, and validate the `compose.yaml` 
-file do not include unsupported features.
-* _Convert_ produces a CloudFormation template to define all resources required to implement the application model on AWS.
-* _Apply_ phase do apply the CloudFormation template, either by exporting to a stack file or to deploy on AWS.  
+* The _Load_ phase relies on
+  [compose-go](https://github.com/compose-spec/compose-go).
+  Any generic code we write for this purpose should be proposed upstream.
+* The _Validate_ phase is responsible for injecting sane ECS defaults into the
+  compose-go model, and validating the `compose.yaml` file does not include
+  unsupported features.
+* The _Convert_ phase produces a CloudFormation template to define all
+  application resources required to implement the application model on AWS.
+* The _Apply_ phase does the actual apply of the CloudFormation template,
+  either by exporting to a stack file or to deploy on AWS.
 
 ## Application model
 
 ### Services
 
-Compose services are mapped to ECS services. Compose specification has no support for multi-container services, nor 
-does it support sidecars. When an ECS feature requires a sidecar, we introduce custom Compose extension (`x-aws-*`)
-to actually expose ECS feature as a service-level feature, not plumbing details.
+Compose services are mapped to ECS services. The Compose specification does not
+have support for multi-container services (like Kubernetes pods) or sidecars.
+When an ECS feature requires a sidecar, we use a custom Compose extension
+(`x-aws-*`) to expose the ECS features as a service-level feature,
+and keep the plumbing details from the user.
 
 ### Networking
 
-We map the "network" abstraction from Compose model to AWS SecurityGroups. The whole application is created within a 
-single VPC, SecurityGroups are created per networks, including the implicit `default` one. Services are attached 
-according to the networks declared in Compose model. Doing so, services attached to a common security group can 
-communicate together, while services from distinct SecurityGroups can't. We just can't set service aliasses per network.
+We map the "network" abstraction from the Compose model to AWS security groups.
+The whole application is created within a single VPC,
+security groups are created per Compose network, including the implicit
+`default` one.
+Services are attached according to the networks declared in Compose model.
+This approach means that services attached to a common security group can
+communicate together, while services from distinct security groups cannot.
+This matches the intent of the Compose network model with the limitation that we
+cannot set service aliases per network.
+
+A [CloudMap](https://aws.amazon.com/cloud-map/) private namespace is created for
+each application as `{project}.local`. Services get registered so that we
+have service discovery and DNS round-robin
+(equivalent to Compose's `endpoint_mode: dnsrr`). Docker images SHOULD include
+an entrypoint script to replicate this feature:
 
-A CloudMap private namespace is created for application as `{project}.local`. Services get registered so that we 
-get service discovery and DNS round-robin (equivalent for Compose's `endpoint_mode: dnsrr`). Docker images SHOULD 
-include a tiny entrypoint script to replicate this feature:
 ```shell script
-if [ ! -z LOCALDOMAIN ]; then echo "search ${LOCALDOMAIN}" >> /etc/resolv.conf; fi 
-```  
-
+if [ ! -z LOCALDOMAIN ]; then echo "search ${LOCALDOMAIN}" >> /etc/resolv.conf; fi
+```