diff --git a/mercurial/helptext/config.txt b/mercurial/helptext/config.txt
--- a/mercurial/helptext/config.txt
+++ b/mercurial/helptext/config.txt
@@ -913,8 +913,28 @@
     Disabled by default.
 
 ``use-share-safe``
-    Enable or disable the "share-safe" functionality, which enables shares
-    to read requirements and configuration of its source repository.
+    Enforce "safe" behaviors for all "share" that access this repository.
+
+    With this feature "share" using this repository as source will:
+
+    * read the source repositories configuration (`<source>/.hg/hgrc`)
+    * read and use the source repositories "requirements"
+      (except the working copy specific one.)
+
+    Without this feature, "share" using this repository as source will:
+
+    * keep tracking the repository "requirements" in the share only, ignoring
+      the source one, possibly diverging from them.
+    * ignore source repository config. This can create problem, like silently
+      ignoring important hooks
+
+    Beware that upgrading/downgrading a repository to use this feature will not
+    affect any of its share. Beware that the existing share will not be upgraded
+    and, by default, Mercurial will refuse to interact with them until the
+    mismatch is resolve. See :hg:`help config share.safe-mismatch.source-safe`
+    and :hg:`help config share.safe-mismatch.source-not-safe` for details.
+
+    Introduced in Mercurial 5.7.
 
     Disabled by default.