docs: examples --> Testable Examples (#761)

* Walk through and explain Testable Examples more

* Walk through and explain Testable Examples more

integers.md

@@ -114,17 +114,15 @@ func Add(x, y int) int {
 }
 ```
 
-### Examples
+### Testable Examples
 
-If you really want to go the extra mile you can make [examples](https://blog.golang.org/examples). You will find a lot of examples in the documentation of the standard library.
+If you really want to go the extra mile you can make [Testable Examples](https://blog.golang.org/examples). You will find many examples in the standard library documentation.
 
-Often code examples that can be found outside the codebase, such as a readme file often become out of date and incorrect compared to the actual code because they don't get checked.
+A common fault in software projects is the documentation examples will become out of date and incorrect, because those examples don't get reviewed, since they exist outside the codebase. Go's Testable Examples solve this problem. 
 
-Go examples are executed just like tests so you can be confident examples reflect what the code actually does.
+Testable Examples are compiled whenever tests are executed. Because such examples are validated by the Go compiler, you can be confident your documentation's examples always reflect current code behavior.
 
-Examples are compiled \(and optionally executed\) as part of a package's test suite.
-
-As with typical tests, examples are functions that reside in a package's `_test.go` files. Add the following `ExampleAdd` function to the `adder_test.go` file.
+Testable functions begin with `Example` (much like test functions begin with `Test`), and reside in a package's `_test.go` files, . Add the following `ExampleAdd` function to the `adder_test.go` file.
 
 ```go
 func ExampleAdd() {
@@ -136,9 +134,9 @@ func ExampleAdd() {
 
 (If your editor doesn't automatically import packages for you, the compilation step will fail because you will be missing `import "fmt"` in `adder_test.go`. It is strongly recommended you research how to have these kind of errors fixed for you automatically in whatever editor you are using.)
 
-If your code changes so that the example is no longer valid, your build will fail.
+Adding this code will cause the example to appear in your `godoc` documentation, making your code even more accessible. If ever your code changes so that the example is no longer valid, your build will fail. 
 
-Running the package's test suite, we can see the example function is executed with no further arrangement from us:
+Running the package's test suite, we can see the example `ExampleAdd` function is executed with no further arrangement from us:
 
 ```bash
 $ go test -v
@@ -148,13 +146,9 @@ $ go test -v
 --- PASS: ExampleAdd (0.00s)
 ```
 
-Please note that the example function will not be executed if you remove the comment `// Output: 6`. Although the function will be compiled, it won't be executed.
-
-By adding this code the example will appear in the documentation inside `godoc`, making your code even more accessible.
-
-To try this out, run `godoc -http=:6060` and navigate to `http://localhost:6060/pkg/`
+Notice the special format of the comment, `// Output: 6`. While the example will always be compiled, adding this comment means the example will also be executed. Go ahead and temporarily remove the comment `// Output: 6`, then run `go test`, and you will see `ExampleAdd` is no longer executed.
 
-Inside here you'll see a list of all the packages and you'll be able to find your example documentation.
+To view example documentation, let's take a quick look at `godoc`. Run `godoc -http=:6060` and open a web browser to `http://localhost:6060/pkg/`. Inside here you'll see a list of all of Go's Standard Library packages, plus Third Party packages you have installed, under which you should see your example documentation for `learn-go-with-tests`. Now look under `Integers`, then under `func Add`, then expand `Example` and you should see the example you added for `sum := Add(1, 5)`.
 
 If you publish your code with examples to a public URL, you can share the documentation of your code at [pkg.go.dev](https://pkg.go.dev/). For example, [here](https://pkg.go.dev/github.com/quii/learn-go-with-tests/integers/v2) is the finalised API for this chapter. This web interface allows you to search for documentation of standard library packages and third-party packages.