diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapConcat.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapConcat.md
index 238a97e81b..5059b9635b 100644
--- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapConcat.md
+++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapConcat.md
@@ -15,6 +15,20 @@ Transform each element into zero or more elements that are individually passed d
 ## Description
 
 Transform each element into zero or more elements that are individually passed downstream.
+This can be used to flatten collections into individual stream elements.
+Returning an empty iterable results in zero elements being passed downstream
+rather than the stream being cancelled.
+
+## Example
+
+The following takes a stream of integers and emits each element twice downstream.
+
+Scala
+:  @@snip [MapConcat.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/MapConcat.scala) { #map-concat }
+
+Java
+:  @@snip [MapConcat.java](/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/MapConcat.java) { #map-concat }
+
 
 ## Reactive Streams semantics
 
diff --git a/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/MapConcat.java b/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/MapConcat.java
new file mode 100644
index 0000000000..e9997474be
--- /dev/null
+++ b/akka-docs/src/test/java/jdocs/stream/operators/sourceorflow/MapConcat.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2019 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators.sourceorflow;
+
+import akka.actor.ActorSystem;
+import akka.stream.javadsl.Source;
+
+import java.util.Arrays;
+
+public class MapConcat {
+  private static ActorSystem system = null;
+
+  // #map-concat
+  Iterable<Integer> duplicate(int i) {
+    return Arrays.asList(i, i);
+  }
+
+  // #map-concat
+
+  void example() {
+    // #map-concat
+    Source.from(Arrays.asList(1, 2, 3))
+        .mapConcat(i -> duplicate(i))
+        .runForeach(System.out::println, system);
+    // prints:
+    // 1
+    // 1
+    // 2
+    // 2
+    // 3
+    // #map-concat
+  }
+}
diff --git a/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/MapConcat.scala b/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/MapConcat.scala
new file mode 100644
index 0000000000..4daff77c68
--- /dev/null
+++ b/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/MapConcat.scala
@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2019 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.sourceorflow
+
+import akka.stream.scaladsl.Source
+
+import scala.concurrent.ExecutionContext
+
+object MapConcat {
+
+  def mapConcat(): Unit = {
+    import akka.actor.ActorSystem
+
+    implicit val system: ActorSystem = ActorSystem()
+    implicit val ec: ExecutionContext = system.dispatcher
+
+    //#map-concat
+    def duplicate(i: Int): List[Int] = List(i, i)
+
+    Source(1 to 3).mapConcat(i => duplicate(i)).runForeach(println)
+    // prints:
+    // 1
+    // 1
+    // 2
+    // 2
+    // 3
+    //#map-concat
+
+  }
+
+}