prometheus · brian-brazil · Mar 6, 2020 · Mar 3, 2020 · Mar 4, 2020
diff --git a/README.md b/README.md
@@ -489,21 +489,60 @@ This comes with a number of limitations:
 
 There's several steps to getting this working:
 
-**One**: Gunicorn deployment
+**1. Gunicorn deployment**:
 
 The `prometheus_multiproc_dir` environment variable must be set to a directory
 that the client library can use for metrics. This directory must be wiped
 between Gunicorn runs (before startup is recommended).
 
-Put the following in the config file:
+This environment variable must be set **from a start-up shell script**,
+and not directly from Python (otherwise it will not propagate to child processes).
+
+**2. Metrics collector**:
+
+The application must initialize a new metrics `CollectorRegistry`,
+and save it within the multi-process collector.
+
+```python
+from prometheus_client import multiprocess
+from prometheus_client import generate_latest, CollectorRegistry, CONTENT_TYPE_LATEST
+
+# Expose metrics.
+def app(environ, start_response):
+    registry = CollectorRegistry()
+    multiprocess.MultiProcessCollector(registry)
+    data = generate_latest(registry)
+    status = '200 OK'
+    response_headers = [
+        ('Content-type', CONTENT_TYPE_LATEST),
+        ('Content-Length', str(len(data)))
+    ]
+    start_response(status, response_headers)
+    return iter([data])
+```
+
+**3. Metrics mode and configuration (Gauge)**:
+
+When `Gauge` metrics are used, additional tuning needs to be performed.
+First of all, the `gunicorn` configuration file need to include the following function:
+
 ```python
 from prometheus_client import multiprocess
 
 def child_exit(server, worker):
     multiprocess.mark_process_dead(worker.pid)
 ```
 
-**Two**: Inside the application
+Second of, metrics instrumentation. Gauges have several modes they can run in,
+which can be selected with the `multiprocess_mode` parameter.
+
+- 'all': Default. Return a timeseries per process alive or dead.
+- 'liveall': Return a timeseries per process that is still alive.
+- 'livesum': Return a single timeseries that is the sum of the values of alive processes.
+- 'max': Return a single timeseries that is the maximum of the values of all processes, alive or dead.
+- 'min': Return a single timeseries that is the minimum of the values of all processes, alive or dead.
+
+Complete example:
 ```python
 from prometheus_client import multiprocess
 from prometheus_client import generate_latest, CollectorRegistry, CONTENT_TYPE_LATEST, Gauge
@@ -527,18 +566,6 @@ def app(environ, start_response):
     return iter([data])
 ```
 
-**Three**: Instrumentation
-
-Counters, Summarys and Histograms work as normal.
-
-Gauges have several modes they can run in, which can be selected with the
-`multiprocess_mode` parameter.
-
-- 'all': Default. Return a timeseries per process alive or dead.
-- 'liveall': Return a timeseries per process that is still alive.
-- 'livesum': Return a single timeseries that is the sum of the values of alive processes.
-- 'max': Return a single timeseries that is the maximum of the values of all processes, alive or dead.
-- 'min': Return a single timeseries that is the minimum of the values of all processes, alive or dead.
 
 ## Parser