=doc add clarification on ActorSelection vs. ActorRef

akka-docs/rst/dev/building-akka.rst

@@ -39,6 +39,7 @@ do is to download and install sbt. You can read more about how to do that in the
 `sbt setup`_ documentation.
 
 .. _sbt: https://github.com/sbt/sbt
+.. _sbt setup: http://www.scala-sbt.org/0.13/tutorial/index.html
 
 The sbt commands that you'll need to build Akka are all included below. If you
 want to find out more about sbt and using it for your own projects do read the

akka-docs/rst/java/lambda-actors.rst

@@ -429,6 +429,18 @@ result:
 
 .. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java#selection-local
 
+.. note::
+
+  It is always preferable to communicate with other Actors using their ActorRef
+  instead of relying upon ActorSelection. Exceptions are
+
+    * sending messages using the :ref:`at-least-once-delivery-java-lambda` facility
+    * initiating first contact with a remote system
+
+  In all other cases ActorRefs can be provided during Actor creation or
+  initialization, passing them from parent to child or introducing Actors by
+  sending their ActorRefs to other Actors within messages.
+
 The supplied path is parsed as a :class:`java.net.URI`, which basically means
 that it is split on ``/`` into path elements. If the path starts with ``/``, it
 is absolute and the look-up starts at the root guardian (which is the parent of

akka-docs/rst/java/untyped-actors.rst

@@ -383,6 +383,18 @@ result:
 
 .. includecode:: code/docs/actor/UntypedActorDocTest.java#selection-local
 
+.. note::
+
+  It is always preferable to communicate with other Actors using their ActorRef
+  instead of relying upon ActorSelection. Exceptions are
+
+    * sending messages using the :ref:`at-least-once-delivery-java` facility
+    * initiating first contact with a remote system
+
+  In all other cases ActorRefs can be provided during Actor creation or
+  initialization, passing them from parent to child or introducing Actors by
+  sending their ActorRefs to other Actors within messages.
+
 The supplied path is parsed as a :class:`java.net.URI`, which basically means
 that it is split on ``/`` into path elements. If the path starts with ``/``, it
 is absolute and the look-up starts at the root guardian (which is the parent of

akka-docs/rst/scala/actors.rst

@@ -421,6 +421,18 @@ result:
 
 .. includecode:: code/docs/actor/ActorDocSpec.scala#selection-local
 
+.. note::
+
+  It is always preferable to communicate with other Actors using their ActorRef
+  instead of relying upon ActorSelection. Exceptions are
+
+    * sending messages using the :ref:`at-least-once-delivery` facility
+    * initiating first contact with a remote system
+
+  In all other cases ActorRefs can be provided during Actor creation or
+  initialization, passing them from parent to child or introducing Actors by
+  sending their ActorRefs to other Actors within messages.
+
 The supplied path is parsed as a :class:`java.net.URI`, which basically means
 that it is split on ``/`` into path elements. If the path starts with ``/``, it
 is absolute and the look-up starts at the root guardian (which is the parent of