diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md
index 137a1bf52f..daa481ce74 100644
--- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md
+++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md
@@ -28,6 +28,14 @@ memory issues. Elements belonging to those keys are drained directly and not sen
 
 @@@
 
+## Example
+
+Scala
+:   @@snip [GroupBy.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/GroupBy.scala) { #groupBy }
+
+Java
+:   @@snip [GroupBy.java](/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java) { #groupBy }
+
 ## Reactive Streams semantics
 
 @@@div { .callout }
diff --git a/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java b/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java
index 2e5a39eceb..5a03a5adab 100644
--- a/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java
+++ b/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java
@@ -477,6 +477,18 @@ class SourceOrFlow {
     // #watch
   }
 
+  void groupByExample() {
+    // #groupBy
+    Source.range(1, 10)
+        .groupBy(2, i -> i % 2 == 0) // create two sub-streams with odd and even numbers
+        .reduce(Integer::sum) // for each sub-stream, sum its elements
+        .mergeSubstreams() // merge back into a stream
+        .runForeach(System.out::println, system);
+    // 25
+    // 30
+    // #groupBy
+  }
+
   static CompletionStage<Done> completionTimeoutExample() {
     // #completionTimeout
     Source<Integer, NotUsed> source = Source.range(1, 100000).map(number -> number * number);
diff --git a/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/GroupBy.scala b/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/GroupBy.scala
new file mode 100644
index 0000000000..89f0202a21
--- /dev/null
+++ b/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/GroupBy.scala
@@ -0,0 +1,25 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.sourceorflow
+
+import akka.actor.ActorSystem
+import akka.stream.scaladsl.Source
+
+object GroupBy {
+
+  def groupBySourceExample(): Unit = {
+    implicit val system: ActorSystem = ???
+    //#groupBy
+    Source(1 to 10)
+      .groupBy(maxSubstreams = 2, _ % 2 == 0) // create two sub-streams with odd and even numbers
+      .reduce(_ + _) // for each sub-stream, sum its elements
+      .mergeSubstreams // merge back into a stream
+      .runForeach(println)
+    //25
+    //30
+    //#groupBy
+  }
+
+}