diff --git a/Docs/ProjectSpec.md b/Docs/ProjectSpec.md
index 820d614a..0774e992 100644
--- a/Docs/ProjectSpec.md
+++ b/Docs/ProjectSpec.md
@@ -375,7 +375,7 @@ A dependency can be one of a 3 types:
 - `framework: path` - links to a framework
 - `carthage: name` - helper for linking to a Carthage framework
 - `sdk: name` - links to a dependency with the SDK. This can either be a relative path within the sdk root or a single filename that references a framework (.framework) or lib (.tbd)
-- `package: name` - links to a Swift Package. The name must match the name of a package defined in the top level`packages`
+- `package: name` - links to a Swift Package. The name must match the name of a package defined in the top level `packages`
 
 **Linking options**:
 
@@ -782,7 +782,7 @@ schemes:
 ## Swift Package
 Swift packages are defined at a project level, and then linked to individual targets via a [Dependency](#dependency).
 
-> Note that Swift Packages don't work in projects with configurations other than Debug and Release
+> Note that Swift Packages don't work in projects with configurations other than `Debug` and `Release`. That limitation is tracked here bugs.swift.org/browse/SR-10927
 
 - [x] **url**: **URL** - the url to the package
 - [x] **version**: **String** - the version of the package to use. It can take a few forms:
diff --git a/Docs/Usage.md b/Docs/Usage.md
index ce810a0d..bbfa63a0 100644
--- a/Docs/Usage.md
+++ b/Docs/Usage.md
@@ -4,9 +4,10 @@
     - [Settings](#settings)
     - [Setting Groups](#setting-groups)
     - [xcconfig files](#xcconfig-files)
-- [Use dependencies](#use-dependencies)
+- [Dependencies](#dependencies)
     - [CocoaPods](#cocoapods)
     - [Carthage](#carthage)
+    - [Swift Package](#swift-package)
     - [SDK](#sdk)
     - [Framework](#framework)
 
@@ -92,7 +93,7 @@ You can also always overide any build settings on CI when building by passing sp
 DEVELOPMENT_TEAM=XXXXXXXXX xcodebuild ...
 ```
 
-# Use dependencies
+# Dependencies
 
 Each target can declare one or more dependencies. See [Dependency](ProjectSpec.md#dependency) in the ProjectSpec for more info about all the properties
 
@@ -153,6 +154,30 @@ options:
   carthageBuildPath: ../../Carthage/Build
 ```
 
+### Swift Package
+Swift Packages can be integrated by defining them at the project level and then referencing them in targets
+
+```yaml
+packages:
+  Yams:
+    url: https://github.com/jpsim/Yams
+    from: 2.0.0
+  SwiftPM:
+    url: https://github.com/apple/swift-package-manager
+    branch: swift-5.0-branch
+targets:
+  App:
+    dependencies:
+      # by default the package product that is linked to is the same as the package name
+      - package: Yams
+      - package: SwiftPM
+      - package: SwiftPM
+        product: SPMUtility # specify a specific product
+```
+If you want to check in the `Package.resolved` file so that everyone is on the same versions, you need to check in `ProjectName.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved`
+
+> Note that Swift Packages don't work in projects with configurations other than `Debug` and `Release`. That limitation is tracked here bugs.swift.org/browse/SR-10927
+
 ### SDK
 System frameworks and libs can be linked by using the `sdk` dependency type. You can either specify frameworks or libs by using a `.framework`, `.tbd` or `dylib` filename, respectively