doc/go_mem.html: don't be clever

Add a short introductory section saying what most Go
programmers really need to know, which is that you
shouldn't have to read this document to understand
the behavior of your program.

LGTM=bradfitz, adg, tracey.brendan, iant, rsc, dsymonds
R=golang-codereviews, bradfitz, tracey.brendan, adg, iant, rsc, dsymonds
CC=golang-codereviews
https://golang.org/cl/158500043

diff --git a/doc/go_mem.html b/doc/go_mem.html
index 2ea1ded7a39fd26806521edd7e84c2a2024a60a4..5dd48ff7fbdea77ccaba39402f0c0c22fcdc1efe 100644 (file)
--- a/doc/go_mem.html
+++ b/doc/go_mem.html
@@ -21,6 +21,29 @@ reads of a variable in one goroutine can be guaranteed to
 observe values produced by writes to the same variable in a different goroutine.
 </p>
 
+
+<h2>Advice</h2>
+
+<p>
+Programs that modify data being simultaneously accessed by multiple goroutines
+must serialize such access.
+</p>
+
+<p>
+To serialize access, protect the data with channel operations or other synchronization primitives
+such as those in the <a href="/pkg/sync/"><code>sync</code></a>
+and <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> packages.
+</p>
+
+<p>
+If you must read the rest of this document to understand the behavior of your program,
+you are being too clever.
+</p>
+
+<p>
+Don't be clever.
+</p>
+
 <h2>Happens Before</h2>
 
 <p>