Edits to intro and installation docs (apollographql#2125)

* Edits to intro and installation docs

* Fix broken links

* Edits from @designatednerd plus new screenshots

docs/shared/carthage-installation-panel.mdx

@@ -11,43 +11,45 @@ import {
 
 <h4>Set up your `Cartfile`</h4>
 
-Add `github "apollographql/apollo-ios"` to your Cartfile. 
+Add `github "apollographql/apollo-ios"` to your Cartfile.
 
 </ExpansionPanelListItem>
 <ExpansionPanelListItem number="2">
 
-<h4>Checkout and build dependencies</h4>
+<h4>Check out and build dependencies</h4>
 
-Run `carthage update --platform ios` (or `--platform ios,macos` to build both Mac and iOS). **NOTE:** There's an issue with the way Carthage uses Lipo in the Xcode 12 GM, please cd into `[YourProject]/Carthage/Checkouts/apollo-ios/scripts` and then run `./carthage-build-workaround.sh` to actually get Carthage builds that work.
+Run `carthage update --use-xcframeworks --platform ios` (or `--platform ios,macos` to build both Mac and iOS).
+
+> **Note:** There's an issue with the way Carthage uses Lipo in the Xcode 12 GM. Please `cd` into `[YourProject]/Carthage/Checkouts/apollo-ios/scripts` and then run `./carthage-build-workaround.sh` to resolve this build issue.
 
 </ExpansionPanelListItem>
-<ExpansionPanelListItem number="3"> 
+<ExpansionPanelListItem number="3">
 
 <h4>Add built frameworks to your project</h4>
 
 Drag and drop `Apollo.framework` from the appropriate `Carthage/Build/iOS` or `Carthage/Build/Mac` folder to the **Embedded Binaries** section of your application target's **General** settings tab. This should also cause them to appear in the **Linked Frameworks And Libraries** section automatically.
-  - If you also plan on using the `ApolloSQLite` library, also drag `ApolloSQLite.framework` and `SQLite.framework` to this area as well.
-  - If you also plan on using the `ApolloWebSocket` library, also drag `ApolloWebSocket.framework` and `Starscream.framework` to this area as well.
+  - To include the `ApolloSQLite` library, also drag `ApolloSQLite.framework` and `SQLite.framework` to this area.
+  - To include the `ApolloWebSocket` library, also drag `ApolloWebSocket.framework` and `Starscream.framework` to this area.
 
 </ExpansionPanelListItem>
 <ExpansionPanelListItem number="4">
 
 <h4>Work around Carthage submission bug</h4>
 
-On your application target's **Build Phases** settings tab, click the **+** icon and choose **New Run Script Phase**. Create a Run Script in which you specify your shell (ex: `bin/sh`), add the following contents to the script area below the shell:
+On your application target's **Build Phases** settings tab, click the **+** icon and choose **New Run Script Phase**. Create a Run Script in which you specify your shell (e.g., `bin/sh`) and add the following contents to the script area below the shell:
 
  ```sh
  /usr/local/bin/carthage copy-frameworks
  ```
 
-and add the paths to the frameworks you want to use under **Input Files**, e.g.:
+Then, add the paths to the frameworks you want to use under **Input Files**, e.g.:
 
  ```
  $(SRCROOT)/Carthage/Build/iOS/Apollo.framework
  ```
- 
-Again, if you're adding `ApolloSQLite` or `ApolloWebSocket`, please make sure to add the other frameworks you added as Input Files. 
- 
+
+Again, if you're adding `ApolloSQLite` or `ApolloWebSocket`, please make sure to add the other frameworks you added as Input Files.
+
 This script works around an [App Store submission bug](http://www.openradar.me/radar?id=6409498411401216) triggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving.
 
 </ExpansionPanelListItem>

docs/shared/carthage-run-script-panel.mdx

@@ -6,13 +6,11 @@ import {
 
 <ExpansionPanel title="Carthage Run Script">
 
-In the never-ending battle of what's going to be more painful when it comes to dependency management, we've decided to make working with Carthage a bit more of a pain in order to make working with NPM way less of a pain. 
+The scripts and binaries that you need to generate code are included in the `Carthage/Checkouts` folder. If this folder is not checked into version control, all developers on a team (and your CI machine) need to run `carthage checkout` when changes are made to the version to ensure they have the correct underlying binaries and scripts.
 
-The scripts and binaries which you need to generate code will be included in the `Carthage/Checkouts` folder. If this folder is not checked into version control, all developers on a team (and your CI machine) will need to run `carthage checkout` when changes are made to the version to ensure they have the correct underlying binaries and scripts.
+Team members can then use this build script:
 
-Once everyone's on the same page about that, you should be able to use this build script:
-
-```sh
+```bash
 # Don't run this during index builds
 if [ $ACTION = "indexbuild" ]; then exit 0; fi
 
@@ -21,4 +19,4 @@ cd "${SRCROOT}/${TARGET_NAME}"
 "${SCRIPT_PATH}"/run-bundled-codegen.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift
 ```
 
-</ExpansionPanel>
+</ExpansionPanel>

docs/shared/pods-installation-panel.mdx

@@ -9,9 +9,9 @@ import {
 <ExpansionPanelList>
 <ExpansionPanelListItem number="1">
 
-<h4>Install CocoaPods</h4>
+<h4>Install or update CocoaPods</h4>
 
-Because Apollo iOS has been written using Swift 5, you need to use version `1.7.0` or higher. You can install CocoaPods using:
+Because Apollo iOS uses Swift 5, you need to use CocoaPods version `1.7.0` or later. You can install CocoaPods with the following command:
 
  ```sh
  gem install cocoapods
@@ -24,8 +24,8 @@ Because Apollo iOS has been written using Swift 5, you need to use version `1.7.
 
 Add `pod "Apollo"` to your Podfile.
 
-  - If you also want to use the `ApolloSQLite` framework, also add `pod "Apollo/SQLite"`
-  - If you also want to use the `ApolloWebSocket` framework, also add `pod "Apollo/WebSocket"`
+  - To include the `ApolloSQLite` framework, also add `pod "Apollo/SQLite"`
+  - To include the `ApolloWebSocket` framework, also add `pod "Apollo/WebSocket"`
 
 </ExpansionPanelListItem>
 <ExpansionPanelListItem number="3">
@@ -43,4 +43,4 @@ Use the `.xcworkspace` file generated by CocoaPods to work on your project.
 </ExpansionPanelListItem>
 </ExpansionPanelList>
 
-</ExpansionPanel>
+</ExpansionPanel>

docs/shared/pods-run-script-panel.mdx

@@ -8,7 +8,7 @@ import {
 
 Our CocoaPods install includes the code-generation scripts and binaries of the `apollo` CLI client as files which will not be added to the framework, but which you can still call from a Run Script Build Phase. Add the following to the Run Script:
 
-```sh
+```bash
 # Don't run this during index builds
 if [ $ACTION = "indexbuild" ]; then exit 0; fi
 
@@ -17,4 +17,4 @@ cd "${SRCROOT}/${TARGET_NAME}"
 "${SCRIPT_PATH}"/run-bundled-codegen.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift
 ```
 
-</ExpansionPanel>
+</ExpansionPanel>

docs/shared/spm-installation-panel.mdx

@@ -6,42 +6,44 @@ import {
 
 <ExpansionPanel title="Swift Package Manager Installation">
 
-**NOTE**: These instructions are intended for usage on Xcode 11 and higher. Xcode 11 is the first version of Xcode that integrates Swift Package manager and makes it _way_ easier to use than it was at the command line. If you are using older versions of Xcode, we recommend using CocoaPods.
+> **Note:** These instructions use the Xcode 13 UI. Xcode 11 is the first version of Xcode that integrates Swift Package manager, whereas older versions require using the command line. If you're using an older version of Xcode, we recommend using CocoaPods instead.
 
 <ExpansionPanelList>
 <ExpansionPanelListItem number="1">
 
-Go to **File > Swift Packages > Add Package Dependency...**
+Go to **File > Add Packages...**
 
-![add a dependency](../source/screenshot/spm_packages_add_dependency.png)
+<img class="screenshot" src="../source/screenshot/spm_packages_add_package.jpg" alt="Adding an SPM package" width="300" />
 
 </ExpansionPanelListItem>
 <ExpansionPanelListItem number="2">
 
-Paste the URL to the Apollo iOS repo on GitHub ([https://github.com/apollographql/apollo-ios.git](https://github.com/apollographql/apollo-ios.git)) into the search bar, then hit the **Next** button: 
+In the dialog that appears, paste the URL of the Apollo iOS GitHub repo (`https://github.com/apollographql/apollo-ios.git`) into the search bar, then select the `apollo-ios` package that appears:
 
-![paste in the url](../source/screenshot/spm_paste_url.png)
+<img class="screenshot" src="../source/screenshot/spm_packages_dialog.jpg" alt="Pasting the Apollo iOS GitHub URL" />
 
 </ExpansionPanelListItem>
 <ExpansionPanelListItem number="3">
 
-Select what version you want to use, then hit next. Xcode will automatically suggest the current version `Up to Next Major`, we **strongly** suggest that while the iOS SDK is on a `0.x.x` version scheme, you select `Up To Next Minor` instead, as we will still be releasing breaking changes on minor versions:
+Select which version you want to use ([see version history](https://github.com/apollographql/apollo-ios/releases)), then click **Add Package**. Note that Xcode might not automatically select the latest version number!
 
-![select a version](../source/screenshot/spm_select_version.png)
+> Xcode automatically suggests the dependency rule `Up to Next Major`. We **strongly** suggest that until the release of Apollo iOS `1.x`, you select `Up To Next Minor` instead, because we might release breaking changes in a minor version.
 
 </ExpansionPanelListItem>
 <ExpansionPanelListItem number="4">
-
-Select which packages you want to use. If you're just getting started, try selecting just the main `Apollo` library first - you can always come back and add the other packages later if you need them. Then hit finish.
 
-![select the packages you want to use](../source/screenshot/spm_select_package.png)
+Select which packages you want to use. If you're getting started, we recommend selecting just the main `Apollo` library for now. You can always add other packages later if you need them.
 
-_Note: Do **not** select the `Apollo-Dynamic` target, this is only for use for projects linking to our library dynamically. Most projects will not need to do this._
+<img class="screenshot" src="../source/screenshot/spm_select_package.jpg" alt="Selecting Apollo iOS packages" />
+
+> **Note:** Do **not** select the `Apollo-Dynamic` target. This target is only for  projects that link to Apollo iOS. Most projects do not need to do this.
+
+Then, click **Add Package**.
 
 </ExpansionPanelListItem>
 <ExpansionPanelListItem number="check">
   You're done!
 </ExpansionPanelListItem>
 </ExpansionPanelList>
 
-</ExpansionPanel>
+</ExpansionPanel>

docs/shared/spm-run-script-panel.mdx

@@ -6,11 +6,11 @@ import {
 
 <ExpansionPanel title="Swift Package Manager Run Script">
 
-> **NOTE**: If your Derived Data is in a custom location, stop, go back, and use the [Swift Scripting](./swift-scripting) method instead. This script relies on Derived Data being in the default location. Swift Scripting doesn't rely on Derived Data at all.
+> **Note:** If your Derived Data is in a custom location, go back and use the [Swift Scripting](./swift-scripting) method instead. This script relies on Derived Data being in the default location. Swift Scripting doesn't rely on Derived Data at all.
 
-If you're using Xcode 11 or higher, SPM will check out the appropriate build script along with the rest of the files when it checks out the repo. Add the following to your Run Script build phase: 
+If you're using Xcode 11 or higher, SPM checks out the appropriate build script along with the rest of the files when it checks out the repo. Add the following to your Run Script build phase:
 
-```sh
+```bash
 # Don't run this during index builds
 if [ $ACTION = "indexbuild" ]; then exit 0; fi
 
@@ -38,6 +38,6 @@ cd "${SRCROOT}/${TARGET_NAME}"
 "${SCRIPT_PATH}"/run-bundled-codegen.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift
 ```
 
-> NOTE: If you try to use this with command line SPM, when you regenerate your `xcodeproj` this build script will get wiped out. We strongly recommend using Xcode 11's built-in SPM handling rather than the command line because of this.
+> **Note:** If you try to use this with command line SPM, when you regenerate your `xcodeproj` this build script will get wiped out. We strongly recommend using Xcode 11's built-in SPM handling instead of the command line because of this.
 
-</ExpansionPanel>
+</ExpansionPanel>

docs/source/downloading-schema.md

@@ -8,13 +8,13 @@ Apollo iOS requires a GraphQL schema file as input to the code generation proces
 
 You can use the [Apollo CLI](https://www.apollographql.com/docs/devtools/cli/) to download a GraphQL schema by sending an introspection query to the server.
 
-If you've installed the CLI globally, you can use the following command to download your schema: 
+If you've installed the CLI globally, you can use the following command to download your schema:
 
 ```sh
 apollo schema:download --endpoint=http://localhost:8080/graphql schema.json
 ```
 
-Note that if you're using the local version set up for codegen, you'll want to use the same method you're using in the [Adding A Code Generation Build Step](installation#adding-a-code-generation-build-step) instructions to access that specific CLI. For example, if you're using CocoaPods, you can set it up like this to download your schema: 
+Note that if you're using the local version set up for codegen, you'll want to use the same method you're using in the [Add a code generation build step](/installation/#5-add-a-code-generation-build-step) instructions to access that specific CLI. For example, if you're using CocoaPods, you can set it up like this to download your schema:
 
 ```sh
 SCRIPT_PATH="${PODS_ROOT}/Apollo/scripts"

docs/source/index.mdx

@@ -1,35 +1,48 @@
 ---
-title: Introduction
+title: Introduction to Apollo iOS
+sidebar_title: Introduction
 description: A strongly-typed, caching GraphQL client for iOS, written in Swift
 ---
 
-[Apollo iOS](https://github.com/apollographql/apollo-ios) is a strongly-typed, caching GraphQL client for native iOS apps written in Swift.
+import { Button } from '@apollo/space-kit/Button';
+import { Link } from 'gatsby';
+import { colors } from 'gatsby-theme-apollo-core';
 
-It allows you to execute queries and mutations against a GraphQL server and returns results as query-specific Swift types. This means you don't have to deal with parsing JSON, or passing around dictionaries and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your UI uses.
+**Apollo iOS** is an [open-source](https://github.com/apollographql/apollo-ios) GraphQL client for native iOS apps, written in Swift. It enables you to execute queries and mutations against a GraphQL server and returns results as operation-specific Swift types.
 
-As the generated types are query-specific, you're only able to access data you actually specify as part of a query. If you don't ask for a field in a particular query, you won't be able to access the corresponding property on the returned data structure.
+<p>
+  <Button
+    color={colors.primary}
+    as={<Link to="/tutorial/tutorial-introduction/" />}
+    style={{marginRight: 16, marginBottom: 16}}
+  >
+    Start the tutorial
+  </Button>
+  <Button
+    as={<Link to="/installation/" />}
+  >
+    Installation
+  </Button>
+</p>
 
-In effect, this means you can now rely on the Swift type checker to make sure errors in data access show up at compile time. With our Xcode integration, you can conveniently work with your UI code and corresponding GraphQL definitions side by side, and it will even validate your query documents, and show errors inline.
+## Benefits
 
-Apollo iOS does more than simply run your queries against a GraphQL server, however. It normalizes query results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run. This means your UI is always internally consistent, and can be kept fully up-to-date with the state on the server with the minimum number of queries required.
+### Strong typing with codegen
 
-This combination of immutable models, one way data flow, and automatic consistency management, leads to a very powerful and elegant programming model that allows you to eliminate common glue code and greatly simplifies app development.
+Thanks to strong typing in Apollo iOS, you don't need to deal with parsing JSON responses or passing around dictionaries of values that require manual casting. You also don't need to write model types yourself, because models are generated from the GraphQL operations your UI defines.
 
-## Getting Started
+Because generated types are operation-specific, they include properties _only_ for the GraphQL fields included in their corresponding operation. This means you can rely on the Swift type checker to flag data access errors at compile time.
 
-We have a [detailed iOS tutorial](./tutorial/tutorial-introduction) walking you through how to build an app called [RocketResever](https://github.com/apollographql/iOSTutorial), which talks to the backend built in the [Fullstack Tutorial](https://www.apollographql.com/docs/tutorial/introduction/).
+Apollo's Xcode integration enables you to work with your UI code and corresponding GraphQL definitions side by side. It even validates your query documents, showing errors inline.
 
-If you have questions or would like to contribute, please join our community at [https://community.apollographql.com/](http://community.apollographql.com/new-topic?category=Help&tags=mobile,client).
+### Normalized caching
 
-## Related platforms
+Apollo iOS normalizes operation results to build a client-side cache of your data, which is updated with every operation you execute. This means your UI is always internally consistent, and it can stay up to date with your backend with as few operation as possible.
 
-[Apollo Android](https://github.com/apollographql/apollo-android) is a GraphQL client for native Android apps written in Java and Kotlin, and offers Kotlin Multi-Platform integration as well.
+[Learn more about caching.](./caching/)
 
-Apollo Client for JavaScript's [React integration](https://apollographql.com/docs/react) works with [React Native](https://facebook.github.io/react-native/) on both iOS and Android.
+## Related libraries
 
-## Other resources
+[Apollo Kotlin](https://www.apollographql.com/docs/kotlin/) is a GraphQL client for native Android apps written in Java and Kotlin. It offers Kotlin Multi-Platform integration as well.
 
-- [GraphQL.org](http://graphql.org) for an introduction and reference to the GraphQL itself, partially written and maintained by the Apollo team.
-- [Our website](http://www.apollographql.com/) to learn about Apollo open-source and commercial tools.
-- [Our blog](https://www.apollographql.com/blog/) for long-form articles about GraphQL, feature announcements for Apollo, and guest articles from the community.
-- [Our Twitter](https://twitter.com/apollographql) for in-the-moment news.
+Apollo Client for JavaScript's [React integration](https://apollographql.com/docs/react) works with [React Native](https://facebook.github.io/react-native/) on both iOS and Android.