Documentation/user-guides: fix comments and add diagram

Documentation/user-guides/cluster-monitoring.md

@@ -2,15 +2,15 @@
 
 This guide is intended to give an introduction to all the parts required to start monitoring a Kubernetes cluster with Prometheus using the Prometheus Operator.
 
-This guide assumes you have a basic understanding of how to use the functionality the Prometheus Operator implements. If you haven't yet we recommend reading through the [getting started guide](getting-started.md) as well as the [alerting guide](alerting.md).
+This guide assumes you have a basic understanding of how to use the functionality the Prometheus Operator implements. If you haven't yet, we recommend reading through the [getting started guide](getting-started.md) as well as the [alerting guide](alerting.md).
 
 ## Metric Sources
 
-Monitoring a Kubernetes cluster with Prometheus is a natural as Kubernetes components themselves are instrumented with Prometheus metrics, therefore those components simply have to be discovered by Prometheus and most of the cluster is monitored.
+Monitoring a Kubernetes cluster with Prometheus is a natural choice as Kubernetes components themselves are instrumented with Prometheus metrics, therefore those components simply have to be discovered by Prometheus and most of the cluster is monitored.
 
-Metrics that are rather about cluster state than a single components metric is exposed by the add-on component [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics).
+Metrics that are rather about cluster state than a single component's metrics is exposed by the add-on component [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics).
 
-Additionally to have an overview of cluster nodes resources the Prometheus [node_exporter](https://github.com/prometheus/node_exporter) is used. The node_exporter allows monitoring a node's resources from CPU, memory and disk utilization and more.
+Additionally, to have an overview of cluster nodes' resources the Prometheus [node_exporter](https://github.com/prometheus/node_exporter) is used. The node_exporter allows monitoring a node's resources: CPU, memory and disk utilization and more.
 
 Once you complete this guide you will monitor the following:
 
@@ -58,9 +58,9 @@ spec:
 
 Once started it ensures that all internal IPs of the nodes in the cluster are synchronized into the specified `Endpoints` object. In this case the object is called `kubelet` and is located in the `kube-system` namespace.
 
-By default every Kubernetes cluster has a `Service` for easy access to the `apiserver`. This is the `Service` called `kubernetes` in the `default` namespace. A `Service` object automatically synchronizes an `Endpoints` object with the targets it selects. Therefore there is nothing, extra to do for Prometheus to be able to discover the `apiserver`.
+By default every Kubernetes cluster has a `Service` for easy access to the API server. This is the `Service` called `kubernetes` in the `default` namespace. A `Service` object automatically synchronizes an `Endpoints` object with the targets it selects. Therefore there is nothing, extra to do for Prometheus to be able to discover the API server.
 
-Aside from the kubelet and the apiserver the other Kubernetes components all run on top of Kubernetes itself. Therefore all that is necessary is to create `Service`s for them for `Endpoints` objects to exist to be able to discover them.
+Aside from the kubelet and the API server the other Kubernetes components all run on top of Kubernetes itself. To discover Kubernetes components that run in a Pod, they simply have to be added to a `Service`.
 
 kube-scheduler:
 
@@ -385,10 +385,10 @@ spec:
   version: v0.5.1
 ```
 
-Read more in the [alerting guide](alerting.md) on how to configure the Alertmanager as it will not spin up unless it has a valid configuration mounted through a `ConfigMap`.
+Read more in the [alerting guide](alerting.md) on how to configure the Alertmanager as it will not spin up unless it has a valid configuration mounted through a `ConfigMap`. Note that the `ConfigMap` has to be in the same namespace as the `Alertmanager` resource as well as have the name `alertmanager-<name-of-alertmanager-object`.
 
 ## Outlook
 
 Once finished with this guide you have an entire monitoring pipeline for Kubernetes. To now access the web UIs they need to be exposed by the Kubernetes cluster, read through the [exposing Prometheus and Alertmanager guide](exposing-prometheus-and-alertmanager.md) to find out how.
 
-Additionally all the manifests here have been collected and together with an initial set of alerting rules and Grafana dashboards all deployable with a single button push in [kube-prometheus](https://github.com/coreos/prometheus-operator/tree/master/contrib/kube-prometheus).
+To help get started more quickly with monitoring Kubernetes clusters, [kube-prometheus](https://github.com/coreos/prometheus-operator/tree/master/contrib/kube-prometheus) was created. It is a collection of manifests including dashboards and alerting rules that can easily be deployed. It utilizes the Prometheus Operator and all the manifests demonstrated in this guide.

Documentation/user-guides/getting-started.md

@@ -1,5 +1,7 @@
 # Prometheus Operator
 
+Operators were introduced by CoreOS as a class of software that operates other software, putting operational knowledge collected by humans into software. Read more in the [original blog post](https://coreos.com/blog/introducing-operators.html).
+
 The mission of the Prometheus Operator is to make running Prometheus on top of Kubernetes as easy as possible, while preserving configurability as well as making the configuration Kubernetes native.
 
 To follow this getting started you will need a Kubernetes cluster you have access to. Let's give the Prometheus Operator a spin:
@@ -39,9 +41,13 @@ The Prometheus Operator introduces third party resources in Kubernetes to declar
 
 > Important for this guide are the `Prometheus` and `ServiceMonitor` resources. Have a look at the [alerting guide](alerting.md) for more information about the `Alertmanager` resource.
 
-The Prometheus resource includes fields such as the desired version of Prometheus to run, the number of replicas, as well as a number of parameters to configure Prometheus itself. The connection of the Prometheus resource to the `ServiceMonitor` is established through the `serviceMonitorSelector`, which selects which `ServiceMonitor`s are to be used to generate the configuration file for Prometheus.
+The `Prometheus` resource declaratively describes the desired state of a Prometheus deployment, while a `ServiceMonitor` describes the set of targets to be monitored by Prometheus.
 
-We will walk through an example application that could look like this:
+![Prometheus Operator Architecture](images/architecture.png "Prometheus Operator Architecture")
+
+The `Prometheus` resource includes a selection of `ServiceMonitors` to be used, this field is called the `serviceMonitorSelector`.
+
+First, deploy three instances of a simple example application, which listens and exposes metrics on port `8080`.
 
 [embedmd]:# (../../example/user-guides/getting-started/example-app-deployment.yaml)
 ```yaml
@@ -64,7 +70,7 @@ spec:
           containerPort: 8080
 ```
 
-Essentially the `ServiceMonitor` has a label selector to select `Service`s and the underlying `Endpoints` objects. For example one might have a `Service` that looks like the following:
+The `ServiceMonitor` has a label selector to select `Service`s and the underlying `Endpoints` objects. The `Service` object for the example application selects the `Pod`s by the `app` label having the `example-app` value. In addition to that the `Service` object specifies the port the metrics are exposed on.
 
 [embedmd]:# (../../example/user-guides/getting-started/example-app-service.yaml)
 ```yaml
@@ -82,7 +88,7 @@ spec:
     port: 8080
 ```
 
-This `Service` object could be discovered by a `ServiceMonitor`.
+This `Service` object is discovered by a `ServiceMonitor`, which selects in the same way. The `app` label must have the value `example-app`.
 
 [embedmd]:# (../../example/user-guides/getting-started/example-app-service-monitor.yaml)
 ```yaml
@@ -100,7 +106,7 @@ spec:
   - port: web
 ```
 
-Finally a `Prometheus` object defines the `serviceMonitorSelector` to specify which `ServiceMonitor`s should be included when generating the Prometheus configuration.
+Finally, a `Prometheus` object defines the `serviceMonitorSelector` to specify which `ServiceMonitor`s should be included. Above the label `team: frontend` was specified, so that's what the `Prometheus` object selects by.
 
 [embedmd]:# (../../example/user-guides/getting-started/prometheus-example.yaml)
 ```yaml
@@ -117,7 +123,9 @@ spec:
       memory: 400Mi
 ```
 
-To be able to access the Prometheus instance it will have to be exposed to the outside somehow. Purely for demonstration purpose we will expose it via a `Service` of type `NodePort`.
+This way the frontend team can create new `ServiceMonitor`s and `Service`s resulting in `Prometheus` to be dynamically reconfigured.
+
+To be able to access the Prometheus instance it will have to be exposed to the outside somehow. For demonstration purpose it will be exposed via a `Service` of type `NodePort`.
 
 [embedmd]:# (../../example/user-guides/getting-started/prometheus-example-service.yaml)
 ```yaml
@@ -143,6 +151,6 @@ Once this `Service` is created the Prometheus web UI is available under the node
 
 Further reading:
 
-* In addition to managing Prometheus clusters the Prometheus Operator can also manage Alertmanager clusters. Learn more in the [alerting guide](alerting.md).
+* In addition to managing Prometheus deployments the Prometheus Operator can also manage Alertmanager clusters. Learn more in the [alerting guide](alerting.md).
 
 * Monitoring the Kubernetes cluster itself. Learn more in the [Cluster Monitoring guide](cluster-monitoring.md).