update documentation for swiftly

Author: matthewbastien

userdocs/userdocs.docc/Articles/Topics/installation.md

@@ -2,6 +2,9 @@
 
 Install the Swift extension via the VS Code Marketplace.
 
-The Swift extension is supported on macOS, Linux, and Windows.
+The Swift extension is supported on macOS, Linux, and Windows. Here's what you will need to do to get set up:
+1. Install Swift from the [Swift.org website](https://www.swift.org/install).
+2. Install [Visual Studio Code](https://code.visualstudio.com/Download).
+3. Install the Swift extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=swiftlang.swift-vscode).
 
-To install, firstly ensure you have [Swift installed on your system](https://www.swift.org/install/). Then [install the Swift extension](https://marketplace.visualstudio.com/items?itemName=swiftlang.swift-vscode). Once your machine is ready, you can get started with the **Swift: Create New Project...** command.
+Once your machine is ready, you can get started with the **Swift: Create New Project...** command.

userdocs/userdocs.docc/Articles/Topics/supported-toolchains.md

@@ -18,14 +18,39 @@ Feature                    | Minimum Toolchain Required
 Debugging with `lldb-dap`  | 6.0
 <doc:docc-live-preview>    | 6.2
 
+## Toolchain Management
+
+The Swift extension will automatically detect installations of the Swift toolchain in your environment. It will look for a `swift` binary available in `PATH` and, if one cannot be found, will prompt you to [install a toolchain from Swift.org](https://www.swift.org/install).
+
+If you have multiple Swift toolchains installed on your system then you can use the command `Swift: Select Toolchain...` to tell the extension which toolchain you would like to use. This will show you a list of all toolchains that VS Code was able to find on your system and let you switch between them.
+
+@Video(
+    source: "toolchain-selection.mp4",
+    alt: "A video showing a VS Code window. The command palette is opened to run the 'Swift: Select toolchain' command which is then used to select Xcode as the preferred toolchain.",
+    poster: "toolchain-selection.png"
+)
+
 ## Swiftly Support
 
-The extension supports toolchains managed by [swiftly](https://github.com/swiftlang/swiftly), the Swift toolchain installer and manager. For instructions on installing swiftly see the [installation instructions on Swift.org](https://www.swift.org/install).
+The extension supports toolchains managed by [swiftly](https://github.com/swiftlang/swiftly), the Swift toolchain installer and manager. This is the recommended way of installing Swift toolchains on macOS and Linux. For instructions on installing swiftly see the [installation instructions on Swift.org](https://www.swift.org/install).
 
-You can choose a swiftly managed toolchain to use from the `> Swift: Select Toolchain` menu.
+You can choose a swiftly managed toolchain to use from the `> Swift: Select Toolchain...` menu.
 
 If you do `swiftly use` on the command line you must restart VS Code or do `> Developer: Reload Window` in order for the VS Code Swift extension to start using the new toolchain.
 
+### Installing Toolchains
+
+The Swift extension can use swiftly to install toolchains on your behalf. This allows you to discover, install, and configure Swift toolchains directly from the VS Code interface without needing to use the command line.
+
+Before using the toolchain installation feature, ensure you meet the following requirements:
+
+* **Swiftly 1.1.0 or newer** - The installation feature requires swiftly version 1.1.0 or newer
+* **Administrator Privileges** - On Linux systems, administrator privileges may be required to execute post-installation scripts
+
+You can access the installation commands via toolchain selection, or by running the following commands directly:
+- **`Swift: Install Swiftly Toolchain...`** - installs stable Swift toolchains via swiftly
+- **`Swift: Install Swiftly Snapshot Toolchain...`** - installs snapshot Swift toolchains via swiftly
+
 ### .swift-version Support
 
 Swiftly can use a special `.swift-version` file in the root of your package so that you can share your toolchain preference with the rest of your team. The VS Code Swift extension respects this file if it exists and will use the toolchain specified within it to build and test your package.