diff --git a/docs/src/cdist-best-practice.rst b/docs/src/cdist-best-practice.rst
index 45aba11b..a99ba88e 100644
--- a/docs/src/cdist-best-practice.rst
+++ b/docs/src/cdist-best-practice.rst
@@ -13,15 +13,18 @@ See sshd_config(5) and ssh-keygen(1).
 Speeding up ssh connections
 ---------------------------
 When connecting to a new host, the initial delay with ssh connections
-is pretty big. You can work around this by
-"sharing of multiple sessions over a single network connection"
-(quote from ssh_config(5)). The following code is suitable for
-inclusion into your ~/.ssh/config::
+is pretty big. As cdist makes many connections to each host successive
+connections can be sped up by "sharing of multiple sessions over a single
+network connection" (quote from ssh_config(5)). This is also called "connection
+multiplexing".
 
-    Host *
-      ControlPath ~/.ssh/master-%l-%r@%h:%p
-      ControlMaster auto
-      ControlPersist 10
+Cdist implements this since v4.0.0 by executing ssh with the appropriate
+options (`-o ControlMaster=auto  -o ControlPath=/tmp/<tmpdir>/s  -o
+ControlPersist=2h`).
+
+Note that the sshd_config on the server can configure the maximum number of
+parallel multiplexed connections this with `MaxSessions N` (N defaults to 10
+for OpenSSH v7.4).
 
 
 Speeding up shell execution
diff --git a/docs/src/cdist-hacker.rst b/docs/src/cdist-hacker.rst
index ea5dceb3..d65c41a6 100644
--- a/docs/src/cdist-hacker.rst
+++ b/docs/src/cdist-hacker.rst
@@ -59,10 +59,9 @@ How to submit a new type
 For detailed information about types, see `cdist type <cdist-type.html>`_.
 
 Submitting a type works as described above, with the additional requirement
-that a corresponding manpage named man.text in asciidoc format with
+that a corresponding manpage named man.rst in ReSTructured text format with
 the manpage-name "cdist-type__NAME" is included in the type directory
-AND asciidoc is able to compile it (i.e. do NOT have to many "=" in the second
-line).
+AND the manpage builds (`make man`).
 
 Warning: Submitting "exec" or "run" types that simply echo their parameter in
 **gencode** will not be accepted, because they are of no use. Every type can output