diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst
index b8e4c7c187ba4..49f2a7a782cfd 100644
--- a/docs/source/command_line.rst
+++ b/docs/source/command_line.rst
@@ -465,8 +465,8 @@ The following flags adjust how mypy handles values of type ``None``.
 
     .. warning::
 
-        ``--no-strict-optional`` is evil. Avoid using it and definitely do
-        not use it without understanding what it does.
+        ``--no-strict-optional`` is not recommended. See
+        :ref:`strict_optional` for an explanation of its behavior.
 
 
 .. _configuring-warnings:
diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst
index d5431b1476aa0..5d99e7e8f0d53 100644
--- a/docs/source/config_file.rst
+++ b/docs/source/config_file.rst
@@ -618,15 +618,15 @@ section of the command line docs.
     :type: boolean
     :default: True
 
-    Effectively disables checking of optional
+    When set to ``false``, effectively disables checking of optional
     types and ``None`` values. With this option, mypy doesn't
     generally check the use of ``None`` values -- it is treated
     as compatible with every type.
 
     .. warning::
 
-        ``strict_optional = false`` is evil. Avoid using it and definitely do
-        not use it without understanding what it does.
+        ``strict_optional = false`` is not recommended. See
+        :ref:`strict_optional` for an explanation of its behavior.
 
 
 Configuring warnings