diff --git a/stdlib/public/core/Result.swift b/stdlib/public/core/Result.swift
index f92818baa5f21..d7276880dbb54 100644
--- a/stdlib/public/core/Result.swift
+++ b/stdlib/public/core/Result.swift
@@ -89,6 +89,25 @@ public enum Result<Success, Failure: Error> {
   /// Returns a new result, mapping any success value using the given
   /// transformation and unwrapping the produced result.
   ///
+  /// Use this method to avoid a nested result when your transformation
+  /// produces another `Result` type.
+  ///
+  /// In this example, note the difference in the result of using `map` and
+  /// `flatMap` with a transformation that returns an result type.
+  ///
+  ///     func getNextInteger() -> Result<Int, Error> {
+  ///         .success(4)
+  ///     }
+  ///     func getNextAfterInteger(_ n: Int) -> Result<Int, Error> {
+  ///         .success(n + 1)
+  ///     }
+  ///
+  ///     let result = getNextInteger().map({ getNextAfterInteger($0) })
+  ///     // result == .success(.success(5))
+  ///
+  ///     let result = getNextInteger().flatMap({ getNextAfterInteger($0) })
+  ///     // result == .success(5)
+  ///
   /// - Parameter transform: A closure that takes the success value of the
   ///   instance.
   /// - Returns: A `Result` instance with the result of evaluating `transform`