--- a/hgext3rd/evolve/__init__.py	Thu Jun 06 13:26:44 2019 +0200
+++ b/hgext3rd/evolve/__init__.py	Thu Jun 06 14:32:25 2019 +0200
@@ -51,39 +51,38 @@
     # re-exchange all markers every time.
     evolution.obsdiscovery = yes
 
-Obsolescence Markers Discovery Experiment
-=========================================
+Obsolescence Markers Discovery
+==============================
 
-We are experimenting with a new protocol to discover common markers between
-local and remote repositories. This experiment is still at an early stage but
-is already raising better results than the previous version (when usable).
+The evolve extension containts an experimental new protocol to discover common
+markers between local and remote repositories.
 
-"Large" repositories (hundreds of thousand) are currently unsupported. Some key
-algorithm has a naive implementation with too aggressive caching, creating
-memory consumption issue (this will get fixed).
+"Large" repositories (hundreds of thousands) will take some time to warm the
+necessary cache. Some key algorithm has a naive implementation that can result
+in large memory or CPU Load.
 
-Medium sized repositories works fine, but be prepared for a noticeable initial
-cache filling. for the Mercurial repository, this is around 20 seconds
-
-The following config control the experiment::
+The following config controls the new protocol::
 
   [experimental]
 
   # enable new discovery protocol
-  # (needed on both client and server)
+  # default to "yes"
   obshashrange = yes
 
   # control cache warming at the end of transaction
-  #   yes:  warm all caches at the end of each transaction,
+  #   yes:  warm all caches at the end of each transaction
+  #         (recommended for server),
   #   off:  warm no caches at the end of transaction,
-  #   auto: warm cache at the end of server side transaction (default).
+  #         (no cache overhead during transaction,
+  #          but cache will be warm from scratch on usage)
+  #   auto: warm cache at the end of server side transaction(ie: push)
+  #         (default).
   obshashrange.warm-cache = 'auto'
 
-    $ hg debugupdatecache
+When you switch to using this protocol, we recommand that you explicitly warm
+cache for your server side repositories.::
 
-It is recommended to enable the blackbox extension. It gathers useful data about
-the experiment. It is shipped with Mercurial so no extra install is needed::
-    $ hg debugupdatecache
+  $ hg debugupdatecache
 
 It is recommended to enable the blackbox extension. It gathers useful data about
 the experiment. It is shipped with Mercurial so no extra install is needed::
@@ -104,7 +103,7 @@
     # ensuring no large repository will get affected.
     obshashrange.max-revs = 100000 # default is None
 
-For very large repositories. it is currently recommended to disable obsmarkers
+For very large repositories, it might be useful to disable obsmarkers
 discovery (Make sure you follow release announcement to know when you can turn
 it back on)::