multiple-ingress.md: rework page for clarity and less repetition

docs/user-guide/multiple-ingress.md

@@ -1,30 +1,10 @@
-# Multiple ingress controllers
+# Multiple Ingress controllers
 
-## Running multiple ingress controllers
+If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,
+you need to specify the annotation `kubernetes.io/ingress.class: "nginx"` in all ingresses that you would like the ingress-nginx controller to claim.
 
-If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress, you need to specify the annotation `kubernetes.io/ingress.class: "nginx"` in all ingresses that you would like this controller to claim.
 
-This mechanism also provides users the ability to run _multiple_ NGINX ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic).  When utilizing this functionality the option `--ingress-class` should be changed to a value unique for the cluster within the definition of the replication controller. Here is a partial example:
-
-```
-spec:
-  template:
-     spec:
-       containers:
-         - name: nginx-ingress-internal-controller
-           args:
-             - /nginx-ingress-controller
-             - '--default-backend-service=ingress/nginx-ingress-default-backend'
-             - '--election-id=ingress-controller-leader-internal'
-             - '--ingress-class=nginx-internal'
-             - '--configmap=ingress/nginx-ingress-internal-controller'
-```
-
-
-## Annotation ingress.class
-
-If you have multiple Ingress controllers in a single cluster, you can pick one by specifying the `ingress.class` 
-annotation, eg creating an Ingress with an annotation like
+For instance,
 
 ```yaml
 metadata:
@@ -44,11 +24,32 @@ metadata:
 
 will target the nginx controller, forcing the GCE controller to ignore it.
 
-__Note__: Deploying multiple ingress controller and not specifying the annotation will result in both controllers fighting to satisfy the Ingress.
+To reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.
+If you are only running a single NGINX ingress controller, this can be achieved by setting the annotation to any value except "nginx" or an empty string.
 
-## Disabling NGINX ingress controller
+Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.
 
-Setting the annotation `kubernetes.io/ingress.class` to any other value  which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.  If you are only running a single NGINX ingress controller, this can be achieved by setting this to any value except "nginx" or an empty string.
+!!! important
+    Deploying multiple Ingress controllers and not specifying a class annotation will
+    result in both or all controllers fighting to satisfy the Ingress, and all of them
+    updating the Ingress status field in confusing ways.
 
-Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.
+## Multiple ingress-nginx controllers
 
+This mechanism also provides users the ability to run _multiple_ NGINX ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic).
+To do this, the option `--ingress-class` must be changed to a value unique for the cluster within the definition of the replication controller.
+Here is a partial example:
+
+```yaml
+spec:
+  template:
+     spec:
+       containers:
+         - name: nginx-ingress-internal-controller
+           args:
+             - /nginx-ingress-controller
+             - '--default-backend-service=ingress/nginx-ingress-default-backend'
+             - '--election-id=ingress-controller-leader-internal'
+             - '--ingress-class=nginx-internal'
+             - '--configmap=ingress/nginx-ingress-internal-controller'
+```