diff --git a/akka-docs/rst/java/code/docs/future/FutureDocTest.java b/akka-docs/rst/java/code/docs/future/FutureDocTest.java
index 667abd8b2b..c37edebbe5 100644
--- a/akka-docs/rst/java/code/docs/future/FutureDocTest.java
+++ b/akka-docs/rst/java/code/docs/future/FutureDocTest.java
@@ -8,6 +8,7 @@ import akka.dispatch.*;
 import scala.concurrent.ExecutionContext;
 import scala.concurrent.Future;
 import scala.concurrent.Await;
+import scala.concurrent.Promise;
 import akka.util.Timeout;
 //#imports1
 
@@ -340,7 +341,7 @@ public class FutureDocTest {
   }
 
   @Test
-  public void useSuccessfulAndFailed() throws Exception {
+  public void useSuccessfulAndFailedAndPromise() throws Exception {
     final ExecutionContext ec = system.dispatcher();
     //#successful
     Future<String> future = Futures.successful("Yay!");
@@ -349,11 +350,18 @@ public class FutureDocTest {
     Future<String> otherFuture = Futures.failed(
       new IllegalArgumentException("Bang!"));
     //#failed
+    //#promise
+    Promise<String> promise = Futures.promise();
+    Future<String> theFuture = promise.future();
+    promise.success("hello");
+    //#promise
     Object result = Await.result(future, Duration.create(5, SECONDS));
     assertEquals("Yay!", result);
     Throwable result2 = Await.result(otherFuture.failed(),
       Duration.create(5, SECONDS));
     assertEquals("Bang!", result2.getMessage());
+    String out = Await.result(theFuture, Duration.create(5, SECONDS));
+    assertEquals("hello", out);
   }
 
   @Test
diff --git a/akka-docs/rst/java/futures.rst b/akka-docs/rst/java/futures.rst
index 862880eb1a..2da3a6b6ba 100644
--- a/akka-docs/rst/java/futures.rst
+++ b/akka-docs/rst/java/futures.rst
@@ -86,6 +86,10 @@ Or failures:
 .. includecode:: code/docs/future/FutureDocTest.java
    :include: failed
 
+It is also possible to create an empty ``Promise``, to be filled later, and obtain the corresponding ``Future``:
+
+.. includecode:: code/docs/future/FutureDocTestBase.java#promise
+
 For these examples ``PrintResult`` is defined as follows:
 
 .. includecode:: code/docs/future/FutureDocTest.java
diff --git a/akka-docs/rst/scala/code/docs/future/FutureDocSpec.scala b/akka-docs/rst/scala/code/docs/future/FutureDocSpec.scala
index cce459ce09..18a8a27caf 100644
--- a/akka-docs/rst/scala/code/docs/future/FutureDocSpec.scala
+++ b/akka-docs/rst/scala/code/docs/future/FutureDocSpec.scala
@@ -399,15 +399,21 @@ class FutureDocSpec extends AkkaSpec {
     }
   }
 
-  "demonstrate usage of Future.successful & Future.failed" in {
+  "demonstrate usage of Future.successful & Future.failed & Future.promise" in {
     //#successful
     val future = Future.successful("Yay!")
     //#successful
     //#failed
     val otherFuture = Future.failed[String](new IllegalArgumentException("Bang!"))
     //#failed
+    //#promise
+    val promise = Promise[String]()
+    val theFuture = promise.future
+    promise.success("hello")
+    //#promise
     Await.result(future, 3 seconds) must be("Yay!")
     intercept[IllegalArgumentException] { Await.result(otherFuture, 3 seconds) }
+    Await.result(theFuture, 3 seconds) must be("hello")
   }
 
   "demonstrate usage of pattern.after" in {
diff --git a/akka-docs/rst/scala/futures.rst b/akka-docs/rst/scala/futures.rst
index 8ec676b263..60093d9d31 100644
--- a/akka-docs/rst/scala/futures.rst
+++ b/akka-docs/rst/scala/futures.rst
@@ -89,6 +89,11 @@ Or failures:
 .. includecode:: code/docs/future/FutureDocSpec.scala
    :include: failed
 
+It is also possible to create an empty ``Promise``, to be filled later, and obtain the corresponding ``Future``:
+
+.. includecode:: code/docs/future/FutureDocSpec.scala
+   :include: promise
+
 Functional Futures
 ------------------