diff --git a/akka-docs/common/code/docs/duration/Java.java b/akka-docs/common/code/docs/duration/Java.java
new file mode 100644
index 0000000000..9b7fb93c3a
--- /dev/null
+++ b/akka-docs/common/code/docs/duration/Java.java
@@ -0,0 +1,26 @@
+/**
+ *  Copyright (C) 2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.duration;
+
+//#import
+import scala.concurrent.util.Duration;
+import scala.concurrent.util.Deadline;
+//#import
+
+class Java {
+  public void demo() {
+    //#dsl
+    final Duration fivesec = Duration.create(5, "seconds");
+    final Duration threemillis = Duration.parse("3 millis");
+    final Duration diff = fivesec.minus(threemillis);
+    assert diff.lt(fivesec);
+    assert Duration.Zero().lt(Duration.Inf());
+    //#dsl
+    //#deadline
+    final Deadline deadline = Duration.create(10, "seconds").fromNow();
+    final Duration rest = deadline.timeLeft();
+    //#deadline
+  }
+}
diff --git a/akka-docs/common/code/docs/duration/Sample.scala b/akka-docs/common/code/docs/duration/Sample.scala
new file mode 100644
index 0000000000..b9e800524e
--- /dev/null
+++ b/akka-docs/common/code/docs/duration/Sample.scala
@@ -0,0 +1,24 @@
+/**
+ *  Copyright (C) 2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.duration
+
+object Scala {
+  //#dsl
+  import scala.concurrent.util.duration._ // notice the small d
+
+  val fivesec = 5.seconds
+  val threemillis = 3.millis
+  val diff = fivesec - threemillis
+  assert(diff < fivesec)
+  val fourmillis = threemillis * 4 / 3 // though you cannot write it the other way around
+  val n = threemillis / (1 millisecond)
+  //#dsl
+
+  //#deadline
+  val deadline = 10.seconds.fromNow
+  // do something
+  val rest = deadline.timeLeft
+  //#deadline
+}
diff --git a/akka-docs/common/duration.rst b/akka-docs/common/duration.rst
index e6bfdd4a36..c159c99a8c 100644
--- a/akka-docs/common/duration.rst
+++ b/akka-docs/common/duration.rst
@@ -5,9 +5,9 @@ Duration
 ########
 
 Durations are used throughout the Akka library, wherefore this concept is
-represented by a special data type, :class:`Duration`. Values of this type may
-represent infinite (:obj:`Duration.Inf`, :obj:`Duration.MinusInf`) or finite
-durations.
+represented by a special data type, :class:`scala.concurrent.util.Duration`.
+Values of this type may represent infinite (:obj:`Duration.Inf`,
+:obj:`Duration.MinusInf`) or finite durations, or be :obj:`Duration.Undefined`.
 
 Finite vs. Infinite
 ===================
@@ -24,18 +24,10 @@ distinguishing the two kinds at compile time:
 Scala
 =====
 
-In Scala durations are constructable using a mini-DSL and support all expected operations:
+In Scala durations are constructable using a mini-DSL and support all expected
+arithmetic operations:
 
-.. code-block:: scala
-
-   import scala.concurrent.util.duration._   // notice the small d
-
-   val fivesec = 5.seconds
-   val threemillis = 3.millis
-   val diff = fivesec - threemillis
-   assert (diff < fivesec)
-   val fourmillis = threemillis * 4 / 3   // though you cannot write it the other way around
-   val n = threemillis / (1 millisecond)
+.. includecode:: code/docs/duration/Sample.scala#dsl
 
 .. note::
 
@@ -50,26 +42,19 @@ Java
 Java provides less syntactic sugar, so you have to spell out the operations as
 method calls instead:
 
-.. code-block:: java
-
-   final Duration fivesec = Duration.create(5, "seconds");
-   final Duration threemillis = Duration.parse("3 millis");
-   final Duration diff = fivesec.minus(threemillis);
-   assert (diff.lt(fivesec));
-   assert (Duration.Zero().lt(Duration.Inf()));
+.. includecode:: code/docs/duration/Java.java#import
+.. includecode:: code/docs/duration/Java.java#dsl
 
 Deadline
 ========
 
-Durations have a brother name :class:`Deadline`, which is a class holding a representation
+Durations have a brother named :class:`Deadline`, which is a class holding a representation
 of an absolute point in time, and support deriving a duration from this by calculating the
 difference between now and the deadline. This is useful when you want to keep one overall
-deadline without having to take care of the book-keeping wrt. the passing of time yourself::
+deadline without having to take care of the book-keeping wrt. the passing of time yourself:
 
-  val deadline = 10 seconds fromNow
-  // do something which takes time
-  awaitCond(..., deadline.timeLeft)
+.. includecode:: code/docs/duration/Sample.scala#deadline
 
-In Java you create these from durations::
+In Java you create these from durations:
 
-  final Deadline d = Duration.create(5, "seconds").fromNow();
+.. includecode:: code/docs/duration/Java.java#deadline