diff --git a/doc/diagnostics.html b/doc/diagnostics.html
index f9d230e6bc..5f82fadcbd 100644
--- a/doc/diagnostics.html
+++ b/doc/diagnostics.html
@@ -317,25 +317,25 @@ create confusion.
 <p><strong>How well do debuggers work with Go programs?</strong></p>
 
 <p>
-As of Go 1.9, the DWARF info generated by the gc compiler is not complete
-and sometimes makes debugging harder. There is an ongoing effort to improve the
-DWARF information to help the debuggers display more accurate information.
-Until those improvements are in you may prefer to disable compiler
-optimizations during development for more accuracy. To disable optimizations,
-use the "-N -l" compiler flags. For example, the following command builds
-a package with no compiler optimizations:
+The <code>gc</code> compiler performs optimizations such as
+function inlining and variable registerization. These optimizations
+sometimes make debugging with debuggers harder. There is an ongoing
+effort to improve the quality of the DWARF information generated for
+optimized binaries. Until those improvements are available, we recommend
+disabling optimizations when building the code being debugged. The following
+command builds a package with no compiler optimizations:
 
 <p>
 <pre>
-$ go build -gcflags="-N -l"
+$ go build -gcflags=all="-N -l"
 </pre>
 </p>
 
-<p>
-As of Go 1.10, the Go binaries will have the required DWARF information
-for accurate debugging. To enable the DWARF improvements, use the following
-compiler flags and use GDB until Delve supports location lists:
-</p>
+As part of the improvement effort, Go 1.10 introduced a new compiler
+flag <code>-dwarflocationlists</code>. The flag causes the compiler to
+add location lists that helps debuggers work with optimized binaries.
+The following command builds a package with optimizations but with
+the DWARF location lists:
 
 <p>
 <pre>