Apply suggestions from code review

Co-authored-by: Joseph Heck <[email protected]>

Author: euanh

Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md

@@ -19,8 +19,12 @@ Find out more and see it in action:
 
 ## Usage
 
-Swift Container Plugin can package any executable product defined in `Package.swift` in a container image and publish it to a container registry.
+Use the Swift Container Plugin to package an executable product from your Swift package into a container image and publish it to a container registry.
 
+To use the plugin:
+- <doc:Adding-the-plugin-to-your-project>
+- <doc:requirements>
+- <doc:authentication>
 ### Build and publish a container image
 
 After adding the plugin to your project, you can build and publish a container image in one step:

Sources/swift-container-plugin/Documentation.docc/authentication.md

@@ -1,10 +1,14 @@
 # Set up your registry credentials
 
-Configure Swift Container Plugin to authenticate to your container registry
+Configure the plugin to authenticate to your container registry.
 
 ## Overview
 
-Many registries require authentication in order to push images, or even pull them.   The plugin can read your registry credentials from a `.netrc` file in your home directory.   You can add a netrc record for each registry you need to use, and the plugin will choose the correct one:
+Many container registries require authentication in order to push images, or even pull them.
+The plugin reads your registry credentials from a `.netrc` file in your home directory.
+Add a record into the `.netrc` file for each registry you use, the plugin uses the authentication by the registry you choose.
+
+The following example shows placeholder values for the registry `registry.example.com`:
 
 ```
 machine registry.example.com

Sources/swift-container-plugin/Documentation.docc/build.md

@@ -2,18 +2,18 @@
 
 ## Overview
 
-`build-container-image` is a command plugin which takes care of building your service, packaging it in a container image and uploading it to a container registry, all in one command:
+The plugin exposes the command `build-container-image` which you invoke to build your service, package it in a container image and upload it to a container registry, in a single command:
 
 ```shell
 % swift package --swift-sdk x86_64-swift-linux-musl \
         build-container-image --from swift:slim --repository registry.example.com/myservice
 ```
 
-* The `--swift-sdk` argument specifies the Swift SDK with which to build the executable.   In this case we are using the Static Linux SDK, which was installed earlier, to build an statically-linked x86_64 Linux binary
+* The `--swift-sdk` argument specifies the Swift SDK with which to build the executable.   In this case we are using the Static Linux SDK, installed earlier, to build an statically-linked x86_64 Linux binary.
 * The `--from` argument specifies the base image on which our service will run.   `swift:slim` is the default, but you can choose your own base image or use `scratch` if your service does not require a base image at all.
 * The `--repository` argument specifies where the plugin will upload our finished image.
 
-The plugin needs permission to connect to the network to publish the image to the registry:
+> Note: on macOS, the plugin needs permission to connect to the network to publish the image to the registry.
 
 ```
 Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports.
@@ -39,4 +39,5 @@ Build of product 'hello-world' complete! (5.51s)
 registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df
 ```
 
-When it finishes, the plugin prints a reference identifying the new image.   Any standard container runtime can use the reference to pull and run your service.
+When the plugin finishes, it prints a reference identifying the new image.
+Any standard container runtime can use the reference to pull and run your service.

Sources/swift-container-plugin/Documentation.docc/requirements.md

@@ -1,6 +1,6 @@
-# Install a toolchain for cross-compilation (macOS)
+# Install a toolchain for cross-compilation
 
-The open source Swift toolchain and a compatible Swift SDK make it possible to build Linux executables on macOS
+Install an open source Swift toolchain and a compatible Swift SDK to build Linux executables on macOS.
 
 ## Overview
 
@@ -20,7 +20,7 @@ If you are running on macOS, you can use a [Swift SDK](https://github.com/apple/
 * Install the [Static Linux SDK from swift.org](https://www.swift.org/documentation/articles/static-linux-getting-started.html)
 * Use [Swift SDK Generator](https://github.com/apple/swift-sdk-generator) to build and install a custom SDK
 
-Let's install the Swift Static Linux SDK:
+The following example illustrates installing the Swift Static Linux SDK:
 ```
 % swift sdk install https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz --checksum 111c6f7d280a651208b8c74c0521dd99365d785c1976a6e23162f55f65379ac6
 Downloading a Swift SDK bundle archive from `https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz`...
@@ -35,7 +35,7 @@ Swift SDK bundle at `https://download.swift.org/swift-6.1-release/static-sdk/swi
 Swift SDK bundle at `https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz` successfully installed as swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.
 ```
 
-Check that the new Swift SDK is now available:
+After the installation is complete, check that the SDK is available:
 
 ```shell
 % swift sdk list