diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 113dc5a0c1..2cd8b96f43 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -137,6 +137,11 @@ project akka-cluster
 multi-jvm:testOnly akka.cluster.SunnyWeather
 ```
 
+### Do not use `-optimize` Scala compiler flag
+
+Akka has not been compiled or tested with `-optimize` Scala compiler flag. (In sbt, you can specify compiler options in the `scalacOptions` key.)
+Strange behavior has been reported by users that have tried it.
+
 ## The `validatePullRequest` task
 
 The Akka build includes a special task called `validatePullRequest` which investigates the changes made as well as dirty
diff --git a/akka-docs/src/main/paradox/scala/scala-compat.md b/akka-docs/src/main/paradox/scala/scala-compat.md
index 2c242c1678..c67471ee38 100644
--- a/akka-docs/src/main/paradox/scala/scala-compat.md
+++ b/akka-docs/src/main/paradox/scala/scala-compat.md
@@ -25,13 +25,4 @@ We will only be able to seamlessly integrate all functional interfaces once
 we can rely on Scala 2.12 to provide full interoperability—this will mean that
 Scala users can directly implement Java Functional Interfaces using lambda syntax
 as well as that Java users can directly implement Scala functions using lambda
-syntax.
-
-## Do not use -optimize Scala compiler flag
-
-@@@ warning
-
-Akka has not been compiled or tested with -optimize Scala compiler flag.
-Strange behavior has been reported by users that have tried it.
-
-@@@
+syntax.
\ No newline at end of file