diff --git a/Documentation/SwiftlyDocs.docc/SwiftlyDocs.md b/Documentation/SwiftlyDocs.docc/SwiftlyDocs.md
index d1f54ae8..39316598 100644
--- a/Documentation/SwiftlyDocs.docc/SwiftlyDocs.md
+++ b/Documentation/SwiftlyDocs.docc/SwiftlyDocs.md
@@ -22,6 +22,8 @@ It provides a single path to install, update, remove, or run commands with a spe
 - <doc:update-toolchain>
 - <doc:automated-install>
 
+- <doc:trouble>
+
 ### Reference
 
 - <doc:swiftly-cli-reference>
diff --git a/Documentation/SwiftlyDocs.docc/trouble.md b/Documentation/SwiftlyDocs.docc/trouble.md
new file mode 100644
index 00000000..c09613da
--- /dev/null
+++ b/Documentation/SwiftlyDocs.docc/trouble.md
@@ -0,0 +1,9 @@
+# Troubleshooting
+
+## Self update swiftly from version 1.1.0 fails with macOS
+
+When trying `swiftly self-update` with the default installation location on macOS, the download succeeds, the initial installation screen appears unexpectedly, and swiftly remains at version 1.1.0.
+
+1. Go to the [swift install page](https://swift.org/install)
+1. Copy the install script
+1. Run the script at the terminal to upgrade to the latest