broad swiftly-doc content edit pass

Documentation/SwiftlyDocs.docc/SwiftlyDocs.md

@@ -6,6 +6,9 @@ Install and manage your Swift programming language toolchains.
     @DisplayName("Swiftly")
 }
 
+Swiftly helps you to easily install different Swift toolchains locally on your account.
+It provides a single path to install, update, remove, or run commands with a specific Swift toolchain.
+
 ## Topics
 
 - <doc:getting-started>

Documentation/SwiftlyDocs.docc/automated-install.md

@@ -1,75 +1,94 @@
-# Install Swiftly Automatically
+# Install swiftly automatically
 
 Automatically install swiftly and Swift toolchains.
 
 This guide helps you to automate the installation of swiftly and toolchains so that it can run unattended, for example in build or continous integration systems.
-We assume that you have working understanding of your build system. The examples are based on a typical Unix environment.
+This guide assumes that you have working understanding of your build system.
+The examples are based on a typical Unix environment.
 
-First, download the swiftly binary from swift.org for your operating system (e.g. Linux) and processor architecture (e.g. arm64, or x86_64). Here's an example using the popular curl command.
+### Download the binary
+
+First, download the swiftly binary from swift.org for your operating system (for example, Linux) and processor architecture (for example `arm64` or `x86_64`).
+Here's an example using the popular curl command.
 
 ```
-curl -L <location_of_swiftly_swift_org> > swiftly.tar.gz
+curl -L https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz > swiftly.tar.gz
 tar zxf swiftly.tar.gz
 ```
 
-On macOS you can download the pkg file and extract it like this from the command-line:
+On macOS, download the pkg file and extract it like this from the command-line:
 
 ```
-curl -L <location_of_swiftly_swift_org> > swiftly.pkg
+curl -L https://download.swift.org/swiftly/darwin/swiftly.pkg > swiftly.pkg
 installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
 ```
 
-> Tip: If you are using Linux you will need the "ca-certificates" package for the root certificate authorities that will establish the trust that swiftly needs to make API requests that it needs. This package is frequently pre-installed on end-user environments, but may not be present in more minimal installations.
+> Tip: If you are using Linux you will need GPG and the "ca-certificates" package for the root certificate authorities that will establish the trust that swiftly needs to make API requests that it needs. This package is frequently pre-installed on end-user environments, but may not be present in more minimal installations.
+
+### Install swiftly
 
-Once swiftly is downloaded you can run the init subcommand to finish the installation. This command will print verbose outputs, assume yes for all prompts, and skip the automatic installation of the latest swift toolchain:
+Once swiftly is downloaded, run the `init` subcommand to finish the installation.
+The following example command prints verbose outputs, assume yes for all prompts, and skips the automatic installation of the latest swift toolchain:
 
 ```
 ./swiftly init --verbose --assume-yes --skip-install    # the swiftly binary is extracted to ~/local/bin/swiftly on macOS
 ```
 
-Swiftly is installed, but the current shell may not yet be updated with the new environment variables, such as the PATH. The init command prints instructions on how to update the current shell environment without opening a new shell. This is an example of the output taken from Linux, but the details might be different for other OSes, username, or shell.
+Swiftly is installed, but the current shell may not yet be updated with the new environment variables, such as `PATH`.
+The `init` command prints instructions on how to update the current shell environment without opening a new shell.
+The following output is an example from Linux, the details might be different for other OSes, username, or shell:
 
 ```
 To begin using installed swiftly from your current shell, first run the following command:
 
 . "/root/.local/share/swiftly/env.sh"
 ```
 
-> Note: on macOS systems you may need to run 'hash -r' to recalculate the zsh PATH cache when installing swiftly and toolchains.
+> Note: on macOS, run 'hash -r' to recalculate the zsh PATH cache when installing swiftly and toolchains.
+
+You can go ahead and add this command to the list of commands in your build script so that the build can proceed to call swiftly from the path. 
+
+### Install a toolchain
 
-You can go ahead and add this command to the list of commands in your build script so that the build can proceed to call swiftly from the path. The usual next step is to install a specific swift toolchain like this:
+The usual next step is to install a specific swift toolchain using the `install` command with the `--post-install-file` option:
 
 ```
 swiftly install 5.10.1 --post-install-file=post-install.sh
 ```
 
-It's possible that there will be some post-installation steps to prepare the build system for using the swift toolchain. The `post-install-file` option gives a file, post-install.sh, that is created if there are post installation steps for this toolchain. You can check if the file exists and run it to perform those final steps. If the build runs as the root user you can check it and run it like this in a typical Unix shell:
+It's possible that there will be some post-installation steps to prepare the system for using the swift toolchain.
+If additional post-install steps are needed to use the toolchain they are written to the file you specified; `post-install.sh` in the example above.
+You can check if the file exists and run it to perform those final steps.
+If the build runs as the root user you can check it and run it like this in a typical Unix shell:
 
 ```
 if [ -f post-install.sh ]; then
     . post-install.sh
 fi
 ```
 
-> Note: If the build system runs your script as a regular user then you will need to take this into account by either pre-installing the toolchain's system dependencies or running the `post-install.sh` script in a secure manner as the administrative user.
+> Note: If the system runs your script as a regular user then you will need to take this into account by either pre-installing the toolchain's system dependencies or running the `post-install.sh` script in a secure manner as the administrative user.
+
+### Customize the installation
 
 If you want to install swiftly, or the binaries that it manages into different locations these can be customized using environment variables before running `swiftly init`.
 
-```
-SWIFTLY_HOME_DIR - The location of the swiftly configuration files, and environment scripts
-SWIFTLY_BIN_DIR - The location of the swiftly binary and toolchain symbolic links (e.g. swift, swiftc, etc.)
-```
+- term `SWIFTLY_HOME_DIR`: The location of the swiftly configuration files, and environment scripts
+- term `SWIFTLY_BIN_DIR`: The location of the swiftly binary and toolchain symbolic links (for example swift, swiftc, and so on)
 
-Sometimes the build system platform can't be automatically detected, or isn't supported by swift. You can provide the platform as an option to the swiftly init subcommand:
+Sometimes swiftly can't automatically detect the system platform, or isn't supported by swift.
+You can provide the platform as an option to the `swiftly init` subcommand:
 
 ```
 swiftly init --platform=<platform_name>
 ```
 
-There are other customizable options, such as overwrite. For more details about the available options, check the help:
+There are other customizable options, such as overwrite.
+For more details about the available options, check the help:
 
 ```
 swiftly init --help
 ```
 
-In summary, swiftly can be installed and install toolchains unattended on build and CI-style systems. This HOWTO guide has outlined the process to script the process covering some of the different options available to you.
+In summary, swiftly can be installed and install toolchains unattended on build and CI-style systems.
+This guide has outlined the process to script the process covering some of the different options available to you.

Documentation/SwiftlyDocs.docc/getting-started.md

@@ -1,15 +1,16 @@
-# Getting Started with Swiftly
+# Getting started with swiftly
 
-Start using swiftly and swift.
+Start using swiftly and Swift.
 
 To get started with swiftly you can download it from [swift.org](https://swift.org/download), and extract the package.
 
 @TabNavigator {
     @Tab("Linux") {
-        If you are using Linux then you can verify and extract the archive like this:
+        If you are using Linux then you can download the binary:
 
         ```
-        tar zxf swiftly-x.y.z.tar.gz
+        curl -L https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz > swiftly.tar.gz
+        tar zxf swiftly.tar.gz
         ```
 
         Now run swiftly init to finish the installation:
@@ -20,21 +21,24 @@ To get started with swiftly you can download it from [swift.org](https://swift.o
     }
 
     @Tab("macOS") {
-        On macOS you can either run the pkg installer from the command-line like this or just run the package by double-clicking on it (not recommended):
+        On macOS you can either run the pkg installer from the command-line like this or run the package by double-clicking on it (not recommended):
 
         ```
-        installer -pkg swift-x.y.z.pkg -target CurrentUserHomeDirectory
+        curl -L https://download.swift.org/swiftly/darwin/swiftly.pkg > swiftly.pkg
+        installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
         ```
 
-        Now run swiftly init to finish the installation:
+        Once the package is installed, run `swiftly init` to finish the installation:
 
         ```
-        ~/usr/local/bin/swiftly init
+        ~/.swiftly/bin/swiftly init
         ```
     }
 }
 
-Swiftly will install itself and download the latest available Swift toolchain. Follow the prompts for any additional steps. Once everything is done you can begin using swift.
+Swiftly installs itself and downloads the latest available Swift toolchain.
+Follow the prompts for any additional steps that may be required.
+Once everything is done you can begin using swift.
 
 ```
 $ swift --version
@@ -72,20 +76,22 @@ Uninstall this toolchain after you're finished with it:
 $ swiftly uninstall main-snapshot
 ```
 
-# Proxy
+## Installing toolchains through an HTTP proxy
 
 Swiftly downloads a list of toolchains from https://www.swift.org/ and retrieves them from CDN via https://download.swift.org.
-If your environment requires a proxy, Swiftly will attempt to use the standard environment variables `http_proxy`, `HTTP_PROXY`, `https_proxy` or `HTTPS_PROXY` to determine which proxy server to use instead of making a direct connection.
+If your environment requires a proxy, Swiftly attempts to use the standard environment variables `http_proxy`, `HTTP_PROXY`, `https_proxy` or `HTTPS_PROXY` to determine which proxy server to use instead of making a direct connection.
 
 To download latest nightly snapshot using a proxy:
 ```
 $ export https_proxy=http://proxy:3128
 $ swiftly install main-snapshot
 ```
 
-# See Also:
+## See Also:
 
+- [Add shell autocompletions](shell-autocompletion)
 - [Install Toolchains](install-toolchains)
 - [Using Toolchains](use-toolchains)
 - [Uninstall Toolchains](uninstall-toolchains)
 - [Swiftly CLI Reference](swiftly-cli-reference)
+

Documentation/SwiftlyDocs.docc/install-toolchains.md

@@ -1,18 +1,21 @@
-# Install Swift Toolchains
+# Install Swift toolchains
 
 Install swift toolchains with Swiftly.
 
-Installing a swift toolchain using swiftly involves downloading it securely and extracting it into a well-known location in your account. Here we will guide you through the different ways you can install a swift toolchain. You will need to install swiftly first. The [Getting Started](getting-started.md) guide is a good place to start with swiftly.
+Installing a swift toolchain using swiftly involves downloading it securely and extracting it into a well-known location in your account.
+This guides you through the different ways you can install a swift toolchain.
+Follow the [Getting Started](getting-started.md) guide to install swiftly.
 
 The easiest way to install a swift toolchain is to select the latest stable release:
 
 ```
 $ swiftly install latest
 ```
 
-> Note: After you install a toolchain there may be certain system dependencies that are needed. Swiftly will provide instructions.
+> Note: After you install a toolchain there may be certain system dependencies that are needed.
+Swiftly provides instructions for any additional dependencies that need to be installed.
 
-If this is the only toolchain that is installed then swiftly will automatically "use" it so that when you run swift (or any other toolchain command) it will be this version.
+If this is the only installed toolchain, swiftly automatically uses it. When you run `swift` (or another toolchain command), it uses the installed version.
 
 ```
 $ swift --version
@@ -21,7 +24,8 @@ Swift version 5.8.1 (swift-5.8.1-RELEASE)
 Target: x86_64-unknown-linux-gnu
 ```
 
-You can be very specific about the released version that you want. We can install the 5.6.1 version like this:
+You can be very specific about the released version to install.
+For example, the following command installs the 5.6.1 toolchain version:
 
 ```
 $ swiftly install 5.6.1
@@ -33,13 +37,13 @@ Once you've installed more than one toolchain you may notice that swift is on th
 $ swiftly use 5.6.1
 ```
 
-You can also combine install and use into one command to automate this process with the `--use` switch on the install subcommand:
+You can combine `install` and `use` into one command with the `--use` switch on the `install` subcommand:
 
 ```
 $ swiftly install --use 5.7.1
 ```
 
-Sometimes you want the latest available patch of a minor release, such as 5.7. Let's omit the patch number so that we get the latest patch.
+Sometimes you want the latest available patch of a minor release, such as 5.7. If you omit the patch number from the release you request, swiftly installs the latest patch.
 
 ```
 $ swiftly install 5.7

Documentation/SwiftlyDocs.docc/shell-autocompletion.md

@@ -1,8 +1,8 @@
-# Add Shell Auto-completions
+# Add shell auto-completions
 
-Generate shell auto-completions for Swiftly.
+Generate shell autocompletions for swiftly.
 
-Swiftly can generate shell auto-completion scripts for your shell to automatically complete subcommands, arguments, options and flags. It does this using the [swift-argument-parser](https://apple.github.io/swift-argument-parser/documentation/argumentparser/installingcompletionscripts/), which has support for Bash, Z shell, and Fish.
+Swiftly can generate shell autocompletion scripts for your shell to automatically complete subcommands, arguments, options and flags. It does this using the [swift-argument-parser](https://apple.github.io/swift-argument-parser/documentation/argumentparser/installingcompletionscripts/), which has support for Bash, Z shell, and Fish.
 
 You can ask swiftly to generate the script using the hidden `--generate-completion-script` flag with the type of shell like this:
 
@@ -63,4 +63,4 @@ swiftly --generate-completion-script <shell>
     }
 }
 
-Once you have installed the completions you can type out a swiftly command, and press a special key (e.g. tab) and the shell will show you the available subcommand, argument, or options to make it easier to assemble a working command-line.
+Once you have installed the completions you can type out a swiftly command, and press a special key (for example, tab) and the shell will show you the available subcommand, argument, or options to make it easier to assemble a working command-line.

Documentation/SwiftlyDocs.docc/uninstall-toolchains.md

@@ -1,8 +1,9 @@
-# Uninstall Swift Toolchains
+# Uninstall Swift toolchains
 
-Uninstall Swift toolchains.
+Remove unneeded Swift toolchains.
 
-After installing several toolchains the list of the available toolchains to use becomes too large. Each toolchain also occupies substantial storage space. It's good to be able to cleanup toolchains when they aren't needed anymore. This guide will cover how to uninstall your toolchains assuming that you have installed swiftly and used it to install them.
+After installing several toolchains the list of the available toolchains may become unwieldy, and each toolchain can occupy substantial storage space.
+This guide covers how to uninstall no longer needed toolchains that were installed with swiftly.
 
 If you have a released version that you want to uninstall then give the exact three digit version (major, minor and patch):
 
@@ -23,14 +24,14 @@ $ swiftly uninstall main-snapshot-2022-08-30
 $ swiftly uninstall 5.7-snapshot-2022-08-30
 ```
 
-It can be time consuming to remove all of the snapshots that you have installed. You can remove all of the snapshots on a version, or main with one command.
+It can be time consuming to remove all of the snapshots that you have installed. You can remove all of the main or version snapshots with one command.
 
 ```
 $ swiftly uninstall main-snapshot
 $ swiftly uninstall 5.7-snapshot
 ```
 
-You can see what toolchahins remain with the list subcommand like this:
+You can see the installed toolchains that remain with the list subcommand:
 
 ```
 $ swiftly list

Documentation/SwiftlyDocs.docc/update-toolchain.md

@@ -1,16 +1,21 @@
-# Update Swift Toolchain
+# Update Swift toolchains
 
-Update swift toolchains.
+Update installed toolchains.
 
-Update replaces a given toolchain with a later version of that toolchain. For a stable release, this means updating to a later patch, minor, or major version. For snapshots, this means updating to the most recently available snapshot. Swiftly can help you to keep up-to-date. We assume that you have installed swiftly and use it to manage your toolchains.
+Update replaces a given toolchain with a later version of that toolchain.
+For a stable release, this means updating to a later patch, minor, or major version. 
+For snapshots, swiftly helps you stay up-to-date by updating to the most recently available snapshot.
+Swiftly only updates toolchains that it installed.
 
-If no version is provided, update will update the currently selected toolchain to its latest patch release if a release toolchain or the latest available snapshot if a snapshot. The newly installed version will be selected.
+If no version is provided, update updates the currently selected toolchain to its latest patch release if a release toolchain, or the latest available snapshot if a snapshot.
+The newly installed version is then activated to use.
 
 ```
 swiftly update
 ```
 
-To update the latest installed release version to the latest available release version, the “latest” version can be provided. Note that this may update the toolchain to the next minor or even major version.
+To update the latest installed release version to the latest available release version, use `latest` as the version. 
+Note that this may update the toolchain to the next minor or even major version.
 
 ```
 swiftly update latest
@@ -28,13 +33,13 @@ If the major and minor version are specified, the latest installed toolchain ass
 swiftly update 5.3
 ```
 
-Similarly, to update the latest snapshot associated with a specific version, the “a.b-snapshot” version can be supplied:
+Similarly, to update the latest snapshot associated with a specific version, append `-snapshot` to the version. For example, the following command updates to the latest 5.3 snapshot version:
 
 ```
 swiftly update 5.3-snapshot
 ```
 
-You can also update the latest installed main snapshot to the latest available one by just providing `main-snapshot`:
+You can also update the latest installed main snapshot to the latest available one by providing `main-snapshot`:
 
 ```
 swiftly update main-snapshot