From a5732307f85b25b6c6f20f59beaa6d2ed698f1b4 Mon Sep 17 00:00:00 2001
From: "s. rannou" <mxs@sbrk.org>
Date: Fri, 21 Jun 2024 11:18:36 +0200
Subject: [PATCH] feat: rework a bit the documentation

---
 README.md | 67 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 38 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index a8df344..e37d02e 100644
--- a/README.md
+++ b/README.md
@@ -64,33 +64,17 @@ Options:
   --help         Show this message and exit.
 ```
 
-## Beacon Compatibility
-
-Beacon type      | Compatibility
------------------|------------------
-Lighthouse       | Full.
-Prysm            | Full.
-Teku             | Not (yet) tested.
-Nimbus           | Not (yet) tested.
-Lodestar         | Not (yet) tested.
-
-The beacon type is relative to the beacon node connected to the
-watcher, **not to the beacon node connected to the validator client
-containing a validator key you want to watch**. The watcher is
-agnostic of the infrastructure mananing validators keys you want to
-watch, this means you can run it on an external location if you want
-blackbox monitoring.
-
 ## Configuration
 
 The configuration uses the YAML format:
 
-```
+```yaml
 # Example config file for the Ethereum validator watcher.
 
 beacon_url: http://localhost:5051/
 beacon_timeout_sec: 90
 network: mainnet
+metrics_port: 8000
 
 watched_keys:
   - public_key: '0xa1d1ad0714035353258038e964ae9675dc0252ee22cea896825c01458e1807bfad2f9969338798548d9858a571f7425c'
@@ -103,25 +87,50 @@ watched_keys:
 
 In this example, we define 3 validators which are running on two
 validator clients in separate regions. The labels can be anything you
-want as long as it follows the 'category:value' format. The breakdown
-dashboard uses it to offer per-value comparisons within a
-category. You can for instance compare your missed attestations
-between region rbx and sbg, or between validator-1 and
-validator-2. This comes handy when operating at scale, you can quickly
-isolate where an issue comes from if your groups match your
+want as long as it follows the `category:value` format. The
+[breakdown dashboard](docs/img/watcher-breakdown.png) uses it to offer
+per-value comparisons within a category. You can for instance compare your
+missed attestations between region `rbx` and `sbg`, or between `validator-1`
+and `validator-2`. This comes handy when operating at scale, you can
+quickly isolate where an issue comes from if your groups match your
 infrastructure.
 
-Any set is possible, some plausible examples:
+Any categories of labels is possible, some plausible examples:
 
 - by beacon instance (i.e: beacon:beacon-1)
 - by client version (i.e: prysm:v5.0.3)
 - by cluster (i.e: cluster:baremetal-1)
 - by operator (i.e: operator:kiln)
 
-By default, the watcher exports the `scope:watched` (keys present in
-the configuration file), `scope:network` (entire network without the
-keys in the configuration file) `scope:all-network` (entire network)
-labels.
+By default, the watcher exports the following labels:
+
+- `scope:watched` for the keys present in the configuration file,
+- `scope:network` for the entire network without the keys in the configuration file,
+- `scope:all-network` for the entire network including the watched keys.
+
+Those are used by the overview dashboard and the breakdown dashboard
+to offer a comparison of your validator keys with the network.
+
+The configuration can be updated in real-time, the watcher will reload
+it dynamically on the next epoch. This allows to have growing sets of
+validators, for instance if you deploy new keys.
+
+## Beacon Compatibility
+
+Beacon type      | Compatibility
+-----------------|------------------
+Lighthouse       | Full.
+Prysm            | Full.
+Teku             | Not (yet) tested.
+Nimbus           | Not (yet) tested.
+Lodestar         | Not (yet) tested.
+
+The beacon type is relative to the beacon node connected to the
+watcher, **not to the beacon node connected to the validator client
+containing a validator key you want to watch**. The watcher is
+agnostic of the infrastructure mananing validators keys you want to
+watch, this means you can run it on an external location if you want
+blackbox monitoring.
 
 ## Installation