diff --git a/akka-docs/rst/java/code/docs/actor/UntypedActorDocTest.java b/akka-docs/rst/java/code/docs/actor/UntypedActorDocTest.java
index 9bfead5b30..1b1b5f105d 100644
--- a/akka-docs/rst/java/code/docs/actor/UntypedActorDocTest.java
+++ b/akka-docs/rst/java/code/docs/actor/UntypedActorDocTest.java
@@ -535,6 +535,31 @@ public class UntypedActorDocTest {
     //#props-factory
   }
 
+  static
+  //#messages-in-companion
+  public class DemoMessagesActor extends UntypedActor {
+
+    static public class Greeting {
+      private final String from;
+
+      public Greeting(String from) {
+        this.from = from;
+      }
+
+      public String getGreeter() {
+        return from;
+      }
+    }
+
+    public void onReceive(Object message) throws Exception {
+      if (message instanceof Greeting) {
+        getSender().tell("Hello " + ((Greeting) message).getGreeter(), getSelf());
+      } else
+        unhandled(message);
+    }
+  }
+  //#messages-in-companion
+
   public static class MyActor extends UntypedActor {
 
     final String s;
diff --git a/akka-docs/rst/java/lambda-actors.rst b/akka-docs/rst/java/lambda-actors.rst
index d13297e0bf..39cac81a82 100644
--- a/akka-docs/rst/java/lambda-actors.rst
+++ b/akka-docs/rst/java/lambda-actors.rst
@@ -130,6 +130,13 @@ a reference to its enclosing scope:
 
 .. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java#props-factory
 
+Another good practice is to declare what messages an Actor can receive
+as close to the actor definition as possible (e.g. as static classes
+inside the Actor or using other suitable class), which makes it easier to know
+what it can receive.
+
+.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java#messages-in-companion
+
 Creating Actors with Props
 --------------------------
 
diff --git a/akka-docs/rst/java/untyped-actors.rst b/akka-docs/rst/java/untyped-actors.rst
index 41d62d63b0..8ae996e4c9 100644
--- a/akka-docs/rst/java/untyped-actors.rst
+++ b/akka-docs/rst/java/untyped-actors.rst
@@ -84,6 +84,13 @@ used constructor actually exists instead relying only on a runtime check.
 
 .. includecode:: code/docs/actor/UntypedActorDocTest.java#props-factory
 
+Another good practice is to declare what messages an Actor can receive
+as close to the actor definition as possible (e.g. as static classes
+inside the Actor or using other suitable class), which makes it easier to know
+what it can receive.
+
+.. includecode:: code/docs/actor/UntypedActorDocTest.java#messages-in-companion
+
 Creating Actors with Props
 --------------------------
 
diff --git a/akka-docs/rst/scala/actors.rst b/akka-docs/rst/scala/actors.rst
index 282fbb29f1..5af764106c 100644
--- a/akka-docs/rst/scala/actors.rst
+++ b/akka-docs/rst/scala/actors.rst
@@ -120,6 +120,12 @@ a reference to its enclosing scope:
 
 .. includecode:: code/docs/actor/ActorDocSpec.scala#props-factory
 
+Another good practice is to declare what messages an Actor can receive
+in the companion object of the Actor, which makes easier
+to know what it can receive:
+
+.. includecode:: code/docs/actor/ActorDocSpec.scala#messages-in-companion
+
 Creating Actors with Props
 --------------------------
 
diff --git a/akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala b/akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala
index 8b942fcdf0..d3f296c332 100644
--- a/akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala
+++ b/akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala
@@ -82,6 +82,24 @@ class DemoActorWrapper extends Actor {
   def receive = Actor.emptyBehavior
 }
 
+class ActorWithMessagesWrapper {
+  //#messages-in-companion
+  object MyActor {
+    case class Greeting(from: String)
+    case object Goodbye
+  }
+  class MyActor extends Actor with ActorLogging {
+    import MyActor._
+    def receive = {
+      case Greeting(greeter) => log.info(s"I was greeted by $greeter.")
+      case Goodbye => log.info("Someone said goodbye to me.")
+    }
+  }
+  //#messages-in-companion
+
+  def receive = Actor.emptyBehavior
+}
+
 class Hook extends Actor {
   var child: ActorRef = _
   //#preStart
diff --git a/akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java b/akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java
index b30085a147..3b29ee5948 100644
--- a/akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java
+++ b/akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java
@@ -152,6 +152,32 @@ public class ActorDocTest {
   }
   //#props-factory
 
+  static
+  //#messages-in-companion
+  public class DemoMessagesActor extends AbstractActor {
+
+    static public class Greeting {
+      private final String from;
+
+      public Greeting(String from) {
+        this.from = from;
+      }
+
+      public String getGreeter() {
+        return from;
+      }
+    }
+
+    DemoMessagesActor() {
+      receive(ReceiveBuilder.
+        match(Greeting.class, g -> {
+          log.info("I was greeted by {}", g.getGreeter());
+        }).build()
+      );
+    };
+  }
+  //#messages-in-companion
+
   public static class Hook extends AbstractActor {
     ActorRef target = null;
     public Hook() {