[ios, osx] Copyedited installation documentation

Copyedited installation documentation to make sense to less experienced Xcode users, ensure consistency, remove redundant language, and reflect recent build changes.

1 files changed, 19 insertions, 8 deletions

diff --git a/platform/ios/DEVELOPING.md b/platform/ios/DEVELOPING.md
index b16ca430a3..3120ff84b5 100644
--- a/platform/ios/DEVELOPING.md
+++ b/platform/ios/DEVELOPING.md
@@ -4,19 +4,21 @@ This document explains how to build the Mapbox iOS SDK from source. It is intend
 
 ### Requirements
 
-The Mapbox iOS SDK and iosapp demo application build against the iOS 7.0 SDK and require Xcode on a computer running OS X.
+The Mapbox iOS SDK and iosapp demo application build against the iOS 7.0 SDK. The SDK is intended to run on iOS 7.0 and above, while iosapp is intended to run on iOS 8.0 and above due to the use of a dynamic framework. Both require Xcode on a computer running OS X.
 
 ### Build
 
 [Install core dependencies](../../INSTALL.md), then run
 
-    make iproj
+```bash
+make iproj
+```
 
-Which will create and open an Xcode workspace that includes both the SDK source and some Objective-C test applications. Before building, use the scheme picker button in the toolbar to change the scheme to “iosapp” and the destination to one of the simulators or connected devices listed in the menu.
+which will create and open an Xcode workspace that includes both the SDK source and some Objective-C test applications. Before building, use the scheme picker button in the toolbar to change the scheme to “iosapp” and the destination to one of the simulators or connected devices listed in the menu.
 
-If you don't have an Apple Developer account, change the destination to a simulator such as "iPhone 6" before you run and build the app.
+If you don’t have an Apple Developer account, change the destination to a simulator such as “iPhone 6s” before you run and build the app.
 
-`ipackage` is only one of several available `make` build targets. Others include:
+`iproj` is only one of several available `make` rules. Others include:
 
 * `make ipackage` builds both dynamic and static frameworks in the Release configuration for devices and the iOS Simulator.
 * `make ipackage-sim` builds a dynamic framework in the Debug configuration for the iOS simulator. This is the fastest target.
@@ -29,17 +31,26 @@ You can customize the build output by passing the following arguments into the `
 * `FORMAT=dynamic` builds only a dynamic framework. `FORMAT=static` builds only a static framework, for compatibility with iOS 7.x.
 * `SYMBOLS=NO` strips the build output of any debug symbols, yielding much smaller binaries.
 
+These targets require that you install [jazzy](https://github.com/realm/jazzy) for generating API documentation:
+
+```bash
+[sudo] gem install jazzy
+```
+
 ### Access tokens
 
 The included applications use Mapbox vector tiles, which require a Mapbox account and API access token. Obtain an access token on the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). You will be prompted for this access token the first time you launch the demo or benchmarking application. In the iOS Simulator, you can paste your access token by pressing Command-V, holding down the left mouse button in the text field, and pressing the Paste button that appears.
 
 ### Test
 
-Run
+`make test-ios` builds and runs unit tests of cross-platform code as well as the SDK.
 
-    make test-ios
+To run these unit tests on the command line, install ios-sim version 3.2.0 (not any other version):
 
-To run the included unit tests and integration tests on the command line.
+```bash
+brew tap mapbox/homebrew-ios-sim-3
+brew install mapbox/homebrew-ios-sim-3/ios-sim
+```
 
 To instead run the tests in Xcode: