=doc #3986 Cluster Singleton should not be used with AutoDown

unless you want each partition of the cluster (effectively new clusters),
to spin up their "own" singleton.

akka-contrib/docs/cluster-singleton.rst

@@ -48,6 +48,26 @@ is able to identify the singleton. It's worth noting that messages can always be
 distributed nature of these actors. As always, additional logic should be implemented in the singleton
 (acknowledgement) and in the client (retry) actors to ensure at-least-once message delivery.
 
+Potential problems to be aware of
+---------------------------------
+
+This pattern may seem to be very tempting to use at first, but it has several drawbacks, some of them are listed below:
+
+* the cluster singleton may quickly become a *performance bottleneck*,
+* you can not rely on the cluster singleton to be *non-stop* available - e.g. when node on which the singleton was running dies,
+  it will take a few seconds for this to be noticed and the singleton be migrated to another node,
+* in the case of a network partition appearing in a Cluster that is using Automatic Downing  (:ref:`automatic-vs-manual-downing-scala`),
+  it may happen that the isolated clusters each decide to spin up their own singleton, meaning that there might be multiple
+  singletons running in the system, yet the Clusters have no way of finding out about them (because of the network partition).
+
+Especially the last point is something you should be aware of - in general when using the Cluster Singleton pattern
+you should take care of downing nodes yourself and not rely on the timing based auto-down feature.
+
+.. warning::
+   **Be very careful when using Cluster Singleton together with Automatic Downing**,
+   since it allows the cluster to split up into two separate clusters, which in turn will result
+   in *multiple Singletons* being started - one in each separate cluster!
+
 An Example
 ----------
 

akka-docs/rst/java/cluster-usage.rst

@@ -111,6 +111,8 @@ cluster or to join the same cluster again. It can use the same host name and por
 after the restart, but it must have been removed from the cluster before the join
 request is accepted.
 
+.. _automatic-vs-manual-downing-java:
+
 Automatic vs. Manual Downing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

akka-docs/rst/scala/cluster-usage.rst

@@ -105,6 +105,8 @@ cluster or to join the same cluster again. It can use the same host name and por
 after the restart, but it must have been removed from the cluster before the join
 request is accepted.
 
+.. _automatic-vs-manual-downing-scala:
+
 Automatic vs. Manual Downing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^