diff --git a/akka-docs/src/test/scala/docs/actor/SharedMutableStateDocSpec.scala b/akka-docs/src/test/scala/docs/actor/SharedMutableStateDocSpec.scala
index 7aaba27ec5..f5b99dab57 100644
--- a/akka-docs/src/test/scala/docs/actor/SharedMutableStateDocSpec.scala
+++ b/akka-docs/src/test/scala/docs/actor/SharedMutableStateDocSpec.scala
@@ -44,33 +44,31 @@ class SharedMutableStateDocSpec {
 
     def receive = {
       case _ =>
-
-        //Wrong ways
         implicit val ec = context.dispatcher
         implicit val timeout = Timeout(5 seconds) // needed for `?` below
 
-        // Very bad, shared mutable state,
-        // will break your application in weird ways
+        // Example of incorrect approach
+        // Very bad: shared mutable state will cause your
+        // application to break in weird ways
         Future { state = "This will race" }
         ((echoActor ? Message("With this other one")).mapTo[Message])
           .foreach { received => state = received.msg }
 
-        // Very bad, shared mutable object,
-        // the other actor cand mutate your own state,
+        // Very bad: shared mutable object allows
+        // the other actor to mutate your own state,
         // or worse, you might get weird race conditions
         cleanUpActor ! mySet
 
-        // Very bad, "sender" changes for every message,
+        // Very bad: "sender" changes for every message,
         // shared mutable state bug
         Future { expensiveCalculation(sender()) }
 
-        //Right ways
-
-        // Completely safe, "self" is OK to close over
+        // Example of correct approach
+        // Completely safe: "self" is OK to close over
         // and it's an ActorRef, which is thread-safe
         Future { expensiveCalculation() } foreach { self ! _ }
 
-        // Completely safe, we close over a fixed value
+        // Completely safe: we close over a fixed value
         // and it's an ActorRef, which is thread-safe
         val currentSender = sender()
         Future { expensiveCalculation(currentSender) }