3 files changed, 74 insertions, 25 deletions
diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md
index eac57bc3de4..a954840b8a6 100644
--- a/doc/user/admin_area/monitoring/health_check.md
+++ b/doc/user/admin_area/monitoring/health_check.md
@@ -1,36 +1,78 @@
 # Health Check
 
-> [Introduced][ce-3888] in GitLab 8.8.
-
-GitLab provides a health check endpoint for uptime monitoring on the `health_check` web
-endpoint. The health check reports on the overall system status based on the status of
-the database connection, the state of the database migrations, and the ability to write
-and access the cache. This endpoint can be provided to uptime monitoring services like
-[Pingdom][pingdom], [Nagios][nagios-health], and [NewRelic][newrelic-health].
+>**Notes:**
+  - Liveness and readiness probes were [introduced][ce-10416] in GitLab 9.1.
+  - The `health_check` endpoint was [introduced][ce-3888] in GitLab 8.8 and will
+    be deprecated in GitLab 9.1. Read more in the [old behavior](#old-behavior)
+    section.
+
+GitLab provides liveness and readiness probes to indicate service health and
+reachability to required services. These probes report on the status of the
+database connection, Redis connection, and access to the filesystem. These
+endpoints [can be provided to schedulers like Kubernetes][kubernetes] to hold
+traffic until the system is ready or restart the container as needed.
 
 ## Access Token
 
-An access token needs to be provided while accessing the health check endpoint. The current
-accepted token can be found on the `admin/health_check` page of your GitLab instance.
+An access token needs to be provided while accessing the probe endpoints. The current
+accepted token can be found under the **Admin area ➔ Monitoring ➔ Health check**
+(`admin/health_check`) page of your GitLab instance.
 
 ![access token](img/health_check_token.png)
 
 The access token can be passed as a URL parameter:
 
 ```
-https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN
+https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN
 ```
 
-or as an HTTP header:
+which will then provide a report of system health in JSON format:
 
-```bash
-curl --header "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json
+```
+{
+  "db_check": {
+    "status": "ok"
+  },
+  "redis_check": {
+    "status": "ok"
+  },
+  "fs_shards_check": {
+    "status": "ok",
+    "labels": {
+      "shard": "default"
+    }
+  }
+}
 ```
 
 ## Using the Endpoint
 
-Once you have the access token, health information can be retrieved as plain text, JSON,
-or XML using the `health_check` endpoint:
+Once you have the access token, the probes can be accessed:
+
+- `https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN`
+- `https://gitlab.example.com/-/liveness?token=ACCESS_TOKEN`
+
+## Status
+
+On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint
+will return a valid successful HTTP status code, and a `success` message.
+
+## Old behavior
+
+>**Notes:**
+  - Liveness and readiness probes were [introduced][ce-10416] in GitLab 9.1.
+  - The `health_check` endpoint was [introduced][ce-3888] in GitLab 8.8 and will
+    be deprecated in GitLab 9.1. Read more in the [old behavior](#old-behavior)
+    section.
+
+GitLab provides a health check endpoint for uptime monitoring on the `health_check` web
+endpoint. The health check reports on the overall system status based on the status of
+the database connection, the state of the database migrations, and the ability to write
+and access the cache. This endpoint can be provided to uptime monitoring services like
+[Pingdom][pingdom], [Nagios][nagios-health], and [NewRelic][newrelic-health].
+
+Once you have the [access token](#access-token), health information can be
+retrieved as plain text, JSON, or XML using the `health_check` endpoint:
 
 - `https://gitlab.example.com/health_check?token=ACCESS_TOKEN`
 - `https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN`
@@ -54,13 +96,13 @@ would be like:
 {"healthy":true,"message":"success"}
 ```
 
-## Status
-
 On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint
 will return a valid successful HTTP status code, and a `success` message. Ideally your
 uptime monitoring should look for the success message.
 
+[ce-10416]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10416
 [ce-3888]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3888
 [pingdom]: https://www.pingdom.com
 [nagios-health]: https://nagios-plugins.org/doc/man/check_http.html
 [newrelic-health]: https://docs.newrelic.com/docs/alerts/alert-policies/downtime-alerts/availability-monitoring
+[kubernetes]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/
diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md
index c3f3179d99e..733e70ca9bf 100644
--- a/doc/user/admin_area/settings/usage_statistics.md
+++ b/doc/user/admin_area/settings/usage_statistics.md
@@ -3,7 +3,7 @@
 GitLab Inc. will periodically collect information about your instance in order
 to perform various actions.
 
-All statistics are opt-in and you can always disable them from the admin panel.
+All statistics are opt-out, you can disable them from the admin panel.
 
 ## Version check
 
diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md
index 1671487bc8c..e25e7a8bbc3 100644
--- a/doc/user/admin_area/user_cohorts.md
+++ b/doc/user/admin_area/user_cohorts.md
@@ -1,30 +1,37 @@
 # Cohorts
 
 > **Notes:**
-- [Introduced][ce-23361] in GitLab 9.1.
+> [Introduced][ce-23361] in GitLab 9.1.
 
 As a benefit of having the [usage ping active](settings/usage_statistics.md),
 GitLab lets you analyze the users' activities of your GitLab installation.
 Under `/admin/cohorts`, when the usage ping is active, GitLab will show the
 monthly cohorts of new users and their activities over time.
 
+## Overview
+
 How do we read the user cohorts table? Let's take an example with the following
 user cohorts.
 
 ![User cohort example](img/cohorts.png)
 
-For the cohort of June 2016, 163 users have been created on this server. One
-month later, in July 2016, 155 users (or 95% of the June cohort) are still
-active. Two months later, 139 users (or 85%) are still active. 9 months later,
-we can see that only 6% of this cohort are still active.
+For the cohort of June 2016, 163 users have been added on this server and have
+been active since this month. One month later, in July 2016, out of
+these 163 users, 155 users (or 95% of the June cohort) are still active. Two
+months later, 139 users (or 85%) are still active. 9 months later, we can see
+that only 6% of this cohort are still active.
+
+The Inactive users column shows the number of users who have been added during
+the month, but who have never actually had any activity in the instance.
 
 How do we measure the activity of users? GitLab considers a user active if:
+
 * the user signs in
 * the user has Git activity (whether push or pull).
 
-### Setup
+## Setup
 
-1. Activate the usage ping as defined [in the documentation](settings/usage_statistics.md)
+1. [Activate the usage ping](settings/usage_statistics.md)
 2. Go to `/admin/cohorts` to see the user cohorts of the server
 
 [ce-23361]: https://gitlab.com/gitlab-org/gitlab-ce/issues/23361