[ios, docs] [ios, docs] Rewrite "Adding points to a map" guide

5 files changed, 37 insertions, 61 deletions

diff --git a/platform/ios/docs/guides/Adding Points to a Map.md b/platform/ios/docs/guides/Adding Points to a Map.md
index 2844075cc7..90951ab0dc 100644
--- a/platform/ios/docs/guides/Adding Points to a Map.md
+++ b/platform/ios/docs/guides/Adding Points to a Map.md
@@ -1,82 +1,58 @@
 # Adding Points to a Map
 
-Mapbox offers a few different ways to add points to a map, each with different tradeoffs.
+## **Annotations API**
 
-## MGLPointAnnotation
+Our annotations API includes the `MGLAnnotationImage`, and `MGLAnnotationView` classes. These are most similar to MapKit’s annotation class and provide a familiar interface for working with markers and callouts.
 
-It’s straightforward to add an annotation to a map. You can use `MGLPointAnnotation` as is, or you can subclass it to add annotations with richer data.
+| ![MGLAnnotationImage](img/adding-points-to-a-map/annotation-image.png "MGLAnnotationImage")               | ![MGLAnnotationView](img/adding-points-to-a-map/annotation-view.png "MGLAnnotationView")              |
+|----------------------|---------------------|
+| `MGLAnnotationImage` | `MGLAnnotationView` |
 
-```swift
-let annotation = MGLPointAnnotation()
-annotation.coordinate = CLLocationCoordinate2D(latitude: 45.5076, longitude: -122.6736)
-annotation.title = "Bobby's Coffee"
-annotation.subtitle = "Coffeeshop"
-mapView.addAnnotation(annotation)
-```
+**MGLAnnotationImage** is an annotation class that is easily customizable with any `UIImage`.
+It is highly performant, as the images are rendered directly in OpenGL. However, if you need to animate your annotations or control z-layer ordering, consider working with **MGLAnnotationView** which supports basic CALayer animations and can be stacked by using `zPosition` property on `CALayer`.
 
-See the `MGLMapViewDelegate` method `-mapView:annotationCanShowCallout:` and similar methods for allowing interaction with a callout ([example](https://www.mapbox.com/ios-sdk/examples/callout-delegate/)).
+**MGLAnnotationView** is an annotation class that is easily customizable with a `UIView`. Use this class if you need your markers to be dynamic or animatable. MGLAnnotationView has a significant advantage over MGLAnnotationImage when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures. However, the map can get slow down when many annotation views are visible at the same time, so if you need to add a very large amount of markers, consider using our runtime styling APIs instead.
 
-## Displaying annotations
+Both MGLAnnotationImage and MGLAnnotationView can become interactive with the addition of a single line of code. When the user taps an annotation, the annotation’s name appears in a basic callout. An annotation view can additionally respond to drag-and-drop gestures.
 
-There are two basic ways to display the annotations you’ve added to a map, each with their own tradeoffs.
+## **Runtime Styling API**
 
-### Annotation Images (`MGLAnnotationImage`)
+For absolute full control of how points are displayed on a map, consider using our [runtime styling](#) APIs. It is the most performant approach for adding hundreds of markers because markers are rendered in GL directly. The runtime styling API provides support for labels rendered together with icons, finer control of z-ordering, and clustering.
 
-Annotation images are the quickest and most performant way to display annotations, but are also the most basic.
+If you need to implement callouts with the runtime styling API, you will need to implement your own tap gesture recognizer that calls `-[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:]` to get the tapped point feature, then show a UIView you provide. Additionally, if you need to animate markers when using the runtime styling APIs, consider using an NSTimer and updating the source data coordinates accordingly.
 
-By default, annotations added to the map are displayed with a red pin ([example](https://www.mapbox.com/ios-sdk/examples/marker/)). To use custom images, you can implement `MGLMapViewDelegate` `-mapView:imageForAnnotation:` ([example](https://www.mapbox.com/ios-sdk/examples/marker-image/)).
+Our runtime styling API is the most powerful option if you need to create rich data visualizations within in your map. This API includes our `MGLSymbolStyleLayer` and `MGLCircleStyleLayer` classes that can be used to dynamically display on markers on map when used in conjunction with either an MGLVectorSource or an MGLShapeSource.
 
-**Pros**
+| ![`MGLCircleStyleLayer`](img/adding-points-to-a-map/circle-layer.png "MGLCircleStyleLayer")               | ![`MGLSymbolStyleLayer`](img/adding-points-to-a-map/symbol-layer.png "MGLSymbolStyleLayer")              |
+|----------------------|---------------------|
+| `MGLCircleStyleLayer` | `MGLSymbolStyleLayer` |
 
-* The easiest way to display a marker on a map
-* Easily customizable with any `UIImage`
-* High performance, as the images are rendered directly in OpenGL
+The **MGLCircleStyleLayer** class is the style layer class responsible for displaying the source’s point features as circle-shaped markers. You can specify circle fill and outline colors, as well as size. You can also dynamically change the circle’s styling properties based on any attributes your source data contains.
 
-**Cons**
+The **MGLSymbolStyleLayer** class is the style layer class responsible for displaying the source’s point features as icons and labels. You can use custom images as icons and also combine text labels, placing them exactly where you specify. You can also dynamically change the symbol’s styling properties based on any attributes your source data contains.
 
-* Annotation images are purely static and cannot be animated
-* No control over z-ordering
+Still undecided on which approach will work best for your use case? Reach out to our support team.
 
-### Annotation Views (`MGLAnnotationView`)
+Mapbox offers a few different ways to add points to a map, each with different tradeoffs. See the table below for a summary of the different approaches:
 
-If you’re looking to add custom `UIView`s or have annotations that are dynamic or animatable, consider an `MGLAnnotationView` instead of an `MGLAnnotationImage` ([example](https://www.mapbox.com/ios-sdk/examples/annotation-views/)).
+✅ Recommended
 
-Annotation views have significant advantages over annotation images when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures.
+⚠️ Supported with caveats
 
-To use annotation views, implement `MGLMapViewDelegate` `-mapView:viewForAnnotation` and provide a custom `MGLAnnotationView` (`UIView`) subclass.
+➖ Unavailable or not supported
 
-**Pros**
 
-* Custom, native UIViews
-* No limit on style or image size
-* Full support for animations
-* Relative control over z-ordering using the `zPosition` property on `CALayer`
-* Familiar API for MapKit users
-
-**Cons**
-
-* Performance implications:
-    * `UIView`s are inherently slow to render compared to OpenGL, more apparent if you’re adding many views or moving the map rapidly
-    * In some cases, you might consider runtime styling
-
-## Advanced: Runtime Styling
-
-For absolute full control of how points are displayed on a map, consider [runtime styling](runtime-styling.html).
-
-You can use `MGLPointFeature` or any other [style primitives](Style%20Primitives.html) to add points and shapes to an `MGLShapeSource`.
-
-From there, you can create one or many `MGLSymbolStyleLayer` or `MGLCircleStyleLayer` layers to filter and style points for display on the map ([example](https://www.mapbox.com/ios-sdk/examples/runtime-multiple-annotations)).
-
-**Pros**
-
-* Most powerful option
-* Highest performance (rendered in GL directly)
-* SDK-level support for labels rendered together with icons
-* Finer control of z-ordering
-    * Rendering respects ordering within the data source
-    * Otherwise layers are lightweight so you can create a new layer for each level you need
-
-**Cons**
-
-* Currently you must implement your own tap gesture recognizer together with `MGLMapView.visibleFeaturesAtPoint` to recognize taps and manually show callouts ([example](https://www.mapbox.com/ios-sdk/examples/select-layer/)).
-* Currently no SDK support for animations. If you need animations, consider using an NSTimer and updating the layer properties accordingly.
+| Feature                                            | MGLAnnotationView                                                  | MGLAnnotationImage                                       | MGLSymbolStyleLayer                                                                                                     | MGLCircleStyleLayer                                                                                                     |
+|----------------------------------------------------|--------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| Customizability                                    | ✅ Text labels, interactive subviews                                | ⚠️ Static images only                                     |  ✅ Full support for text labels and label placement                                                                     |  ✅Customize circle color and outline                                                                                    |
+| Borrows familiar concepts from                     | MapKit, Google Maps SDK                                            | ➖                                                        | Mapbox GL JS, Mapbox Studio                                                                                             | Mapbox GL JS, Mapbox Studio                                                                                             |
+| Can use images                                     | ✅                                                                  | ✅                                                        | ✅                                                                                                                       | ➖                                                                                                                       |
+| Can use text                                       | ✅                                                                  | ➖                                                        | ✅                                                                                                                       | ➖                                                                                                                       |
+| Control Z-index                                    | ✅                                                                  | ➖                                                        | ⚠️ Add multiple layers at, above, or below a specified layer index to control ordering                                   | ⚠️ Add multiple layers at, above, or below a specified layer index to control ordering                                   |
+| Drag and drop                                      | ✅                                                                  | ➖                                                        | ➖                                                                                                                       | ➖                                                                                                                       |
+| Core Animation support                             | ✅                                                                  | ➖                                                        | ➖                                                                                                                       | ➖                                                                                                                       |
+| Add/move/replace data                              | ✅                                                                  | ✅                                                        | ⚠️ Partial data updates are less performant than using annotations                                                       | ⚠️ Partial data updates are less performant than using annotations                                                       |
+| SceneKit support                                   | ✅                                                                  | ➖                                                        | ➖                                                                                                                       | ➖                                                                                                                       |
+| Can be dynamically styled based on data attributes |  ✅ Subclass `MGLPointAnnotation` to add custom attributes          | ✅ Subclass `MGLPointAnnotation` to add custom attributes | ✅                                                                                                                       | ✅                                                                                                                       |
+| Supports callouts                                  |  ✅ Built-in callouts included                                      | ✅ Built-in callouts included                             | ⚠️ Implement your own gesture recognizer that uses feature querying, then create custom UIViews to mimic native callouts | ⚠️ Implement your own gesture recognizer that uses feature querying, then create custom UIViews to mimic native callouts |
+| Supports clustering                                | ⚠️ Use a [third-party plugin](https://github.com/hulab/ClusterKit/) | ➖                                                        | ✅                                                                                                                       | ✅                                                                                                                       |
diff --git a/platform/ios/docs/img/adding-points-to-a-map/annotation-image.png b/platform/ios/docs/img/adding-points-to-a-map/annotation-image.png
new file mode 100644
index 0000000000..71cfeea622
--- /dev/null
+++ b/platform/ios/docs/img/adding-points-to-a-map/annotation-image.png
diff --git a/platform/ios/docs/img/adding-points-to-a-map/annotation-view.png b/platform/ios/docs/img/adding-points-to-a-map/annotation-view.png
new file mode 100644
index 0000000000..7d91e7cf67
--- /dev/null
+++ b/platform/ios/docs/img/adding-points-to-a-map/annotation-view.png
diff --git a/platform/ios/docs/img/adding-points-to-a-map/circle-layer.png b/platform/ios/docs/img/adding-points-to-a-map/circle-layer.png
new file mode 100644
index 0000000000..c7d5f8adde
--- /dev/null
+++ b/platform/ios/docs/img/adding-points-to-a-map/circle-layer.png
diff --git a/platform/ios/docs/img/adding-points-to-a-map/symbol-layer.png b/platform/ios/docs/img/adding-points-to-a-map/symbol-layer.png
new file mode 100644
index 0000000000..cbea906123
--- /dev/null
+++ b/platform/ios/docs/img/adding-points-to-a-map/symbol-layer.png