diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 1e9ed6e645a..21ba0b5cebc 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -260,12 +260,23 @@ Miscellaneous options
 
 .. cmdoption:: -O
 
-   Turn on basic optimizations.  See also :envvar:`PYTHONOPTIMIZE`.
+   Remove assert statements and any code conditional on the value of
+   :const:`__debug__`.  Augment the filename for compiled
+   (:term:`bytecode`) files by adding ``.opt-1`` before the ``.pyc``
+   extension (see :pep:`488`).  See also :envvar:`PYTHONOPTIMIZE`.
+
+   .. versionchanged:: 3.5
+      Modify ``.pyc`` filenames according to :pep:`488`.
 
 
 .. cmdoption:: -OO
 
-   Discard docstrings in addition to the :option:`-O` optimizations.
+   Do :option:`-O` and also discard docstrings.  Augment the filename
+   for compiled (:term:`bytecode`) files by adding ``.opt-2`` before the
+   ``.pyc`` extension (see :pep:`488`).
+
+   .. versionchanged:: 3.5
+      Modify ``.pyc`` filenames according to :pep:`488`.
 
 
 .. cmdoption:: -q
diff --git a/Misc/NEWS.d/next/Documentation/2018-02-23-12-48-03.bpo-17232.tmuTKL.rst b/Misc/NEWS.d/next/Documentation/2018-02-23-12-48-03.bpo-17232.tmuTKL.rst
new file mode 100644
index 00000000000..5c14e91b391
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-02-23-12-48-03.bpo-17232.tmuTKL.rst
@@ -0,0 +1 @@
+Clarify docs for -O and -OO.  Patch by Terry Reedy.
diff --git a/Misc/python.man b/Misc/python.man
index 0f38c5b12ce..a0084f84d04 100644
--- a/Misc/python.man
+++ b/Misc/python.man
@@ -164,10 +164,13 @@ for the named module and runs the corresponding
 file as a script.
 .TP
 .B \-O
-Turn on basic optimizations.  Given twice, causes docstrings to be discarded.
+Remove assert statements and any code conditional on the value of
+__debug__; augment the filename for compiled (bytecode) files by
+adding .opt-1 before the .pyc extension.
 .TP
 .B \-OO
-Discard docstrings in addition to the \fB-O\fP optimizations.
+Do \fB-O\fP and also discard docstrings; change the filename for
+compiled (bytecode) files by adding .opt-2 before the .pyc extension.
 .TP
 .B \-q
 Do not print the version and copyright messages. These messages are
diff --git a/Modules/main.c b/Modules/main.c
index 1ce075f98e3..f6b51043007 100644
--- a/Modules/main.c
+++ b/Modules/main.c
@@ -96,8 +96,10 @@ static const char usage_2[] = "\
          if stdin does not appear to be a terminal; also PYTHONINSPECT=x\n\
 -I     : isolate Python from the user's environment (implies -E and -s)\n\
 -m mod : run library module as a script (terminates option list)\n\
--O     : optimize generated bytecode slightly; also PYTHONOPTIMIZE=x\n\
--OO    : remove doc-strings in addition to the -O optimizations\n\
+-O     : remove assert and __debug__-dependent statements; add .opt-1 before\n\
+         .pyc extension; also PYTHONOPTIMIZE=x\n\
+-OO    : do -O changes and also discard docstrings; add .opt-2 before\n\
+         .pyc extension\n\
 -q     : don't print version and copyright messages on interactive startup\n\
 -s     : don't add user site directory to sys.path; also PYTHONNOUSERSITE\n\
 -S     : don't imply 'import site' on initialization\n\