Update documentation for swiftly (#1905)

Author: matthewbastien

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

@@ -2,6 +2,11 @@
 
 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. To set it 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 start writing Swift code:
+ * Use the **`Swift: Create New Project...`** command from the command palette to initialize a new project.
+ * Navigate to **`File > Open Folder`** in the menu bar to open an existing project on your machine.

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 automatically detects installations of the Swift toolchain in your environment. It looks for a `swift` binary available in `PATH` and, if one cannot be found, prompts you to [install a toolchain from Swift.org](https://www.swift.org/install).
+
+If you have multiple Swift toolchains installed on your system, use the command `Swift: Select Toolchain...` to tell the extension which toolchain to use. The command shows you a list of all the toolchains that VS Code found on your system and lets 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). There is also a [getting started guide for swiftly on Swift.org](https://www.swift.org/swiftly/documentation/swiftly/getting-started/).
 
-You can choose a swiftly managed toolchain to use from the `> Swift: Select Toolchain` menu.
+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. Run **`swiftly self-update`** in your terminal to get the latest version of swiftly.
+* **Administrator Privileges** - On Linux systems, `sudo` may be required to install system dependencies for the toolchain after installation.
+
+You can access the installation commands via the `Swift: Select Toolchain...` command, 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.